Arcgis Victoria

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

The description adds significant behavioral context beyond annotations: default model is free, Anthropic requires BYO key (cost implication), returns per-model {score, confidence, signals, raw_response} plus combined view. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, and the description does not contradict them.

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

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

The description is two well-structured sentences. The first sentence states purpose and output, the second adds key details on defaults and return format. Every sentence earns its place with no waste.

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 4 parameters (all documented in schema), no output schema, and no nested objects, the description provides a useful summary of return shape (per-model + combined view) and special behavior (free vs paid). It is adequate but could optionally detail the combined view structure.

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

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

Schema coverage is 100% with all parameters described. The description reinforces that default model is free and _apiKey is for Anthropic, but does not add meaning beyond the schema. Baseline score of 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the tool probes LLMs for awareness of an entity and scores visibility (0-100) per model. It specifies the verb 'probe' and 'score', the resource 'LLMs' and 'visibility', and distinguishes from sibling tools like scan_competitor_ai_presence and entity_profile by its multi-model scoring approach.

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 usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model usage and optional API key for Anthropic. While it does not explicitly state when not to use or contrast with siblings, the context is clear enough for an agent to decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it reveals that the tool routes questions to other tools, fills arguments automatically, returns stable citation URIs, works on every tier, and makes one fast call. This goes beyond the annotations without contradicting them.

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

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

The description is long but every section earns its place: preference over web search, routing behavior, example queries, default status, and escalation paths. It is front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and organized so an agent can quickly extract decision-relevant guidance. Slightly verbose but not wasteful.

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 an open-ended query tool with no output schema, the description is remarkably complete: it defines the input type, the routing behavior, the output format (structured answer with citations), the coverage scope, and the conditions for choosing alternatives. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, with all six parameters described as aliases for the same 'question' field, so the schema already carries the parameter meaning. The description adds examples of valid questions and notes that input is natural language, but it doesn't add material semantic detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as the default entry point for factual questions, explicitly contrasting it with web search and naming sibling tools like ask_pipeworx_grounded and deep_research. It specifies the resource (5,695 tools across 1,491 sources) and the deliverable (structured answer with citation URIs), making its 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?

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and concrete trigger phrases like 'what is', 'look up', and 'current'. It also clearly states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), giving the agent actionable routing logic.

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

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

The description richly discloses behavioral traits beyond the annotations: it explains the beta/experimental status, notes that no candidate is currently active so behavior matches ask_pipeworx exactly, and clarifies that it falls back to nothing but remains a fully working router. This gives the agent confidence in edge cases without contradicting the readOnly/idempotent/openWorld hints.

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

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

The description is slightly long but every sentence carries meaningful caveats: beta status, current absence of an active candidate, comparison behavior, and full router fallback. The specific retirement date is a minor redundancy that could be trimmed, but overall it is well-structured and front-loaded.

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

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

For a simple question-answering router with no output schema, the description covers the essential context: it is a full working tool, how it differs from the stable router, and its current state. The only minor gap is that it relies on the reader knowing ask_pipeworx's response shape, but the reference to identical behavior mitigates this.

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%, and the input schema already documents the 'question' parameter and its aliases. The description adds no parameter-specific detail beyond saying 'same arguments', so the baseline 3 applies.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, an identical universal router with the same 5,695 tools and response shape. It distinguishes it from the stable sibling by its experimental nature, though it assumes some prior knowledge of what ask_pipeworx actually does.

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: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also contrasts it with the stable router by mentioning results are compared to decide what merges, giving the agent a clear decision point.

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 a safe read-only, idempotent operation. The description adds substantial behavioral context beyond that: it documents the structured success response, the explicit refusal contract, all refusal reasons, the verbatim evidence guarantee, and the extra LLM-call cost. This fully discloses the tool's decision-making 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 dense but every sentence earns its place: mode differentiation, routing mechanism, return contract on success, return contract on refusal, use cases, and cost trade-off. It is front-loaded with the most decision-relevant distinction and has no filler.

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

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

Because there is no output schema, the description fully compensates by specifying the exact success payload and the refusal payload with enumerated reasons. It also covers routing scope, evidence behavior, and the trade-off against the sibling tool. An agent has everything needed to select and invoke this 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 description coverage is 100%; every parameter including aliases already documents itself as 'Alias for question.' The description adds no additional parameter-level meaning. With the schema doing the heavy lifting, the baseline of 3 is appropriate.

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

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

The description leads with a specific, differentiated function: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes this tool from ask_pipeworx by explaining that it extracts answers using ONLY the tool result content. It also names the sibling it parallels, so an agent can immediately tell them apart.

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 gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on, and when the agent must not invent facts. It also gives explicit when-not-to-use guidance: prefer ask_pipeworx for casual lookups because this mode costs an extra LLM call. This is model routing 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 discloses extensive behavioral traits beyond annotations, including fan-out logic, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, market status handling, and cancellation rule parsing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and supplemented with critical operational 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 verbose and densely packed with information over multiple paragraphs. While it front-loads the core purpose, the extensive detail on classifiers, examples, response shapes, and edge cases could be better structured for conciseness. It earns its length but sacrifices brevity.

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

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

Given the tool's complexity (multiple classifiers, fan-out, varied response scenarios), the description is remarkably thorough. It covers all critical aspects: market matching, parent events, news fallback mechanisms, safety features, illiquidity, cancellation rules. Without an output schema, the description adequately addresses return values and edge cases.

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

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

All three parameters (market, depth, include_raw) have schema descriptions, but the description adds significant meaning: input types for market, default and effect for depth, and a detailed explanation for include_raw (response size trade-offs). This enriches semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question), the process (resolve, classify, fan-out), and output (evidence packet + comparison). This is a specific verb+resource with detailed scope, distinguishing it from siblings by its unique functionality.

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

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

The description provides clear usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly state when NOT to use this tool or suggest alternatives among the sibling tools, which would improve guidance.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: for type='company' it pulls latest 10-K financials from SEC EDGAR/XBRL with off-calendar fiscal year handling; for type='drug' it pulls FAERS adverse events, FDA approvals, trial counts; results are sorted by primary metric; returns paired data with citation URIs. No contradiction.

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

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

The description is moderately lengthy but packs useful information in a structured way using example phrases and bullet-like enumeration. Every sentence adds value; it is not overly verbose. Could be slightly more concise, but effective.

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

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

Despite lacking an output schema, the description adequately covers return values (paired data + citation URIs). It explains the two data types, entity count limits, and efficiency advantage. No missing critical information for a tool of this complexity.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema by providing examples of values (tickers/CIKs for company, drug names) and constraints (2-5, maxItems 5). It also explains the data sources per type.

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 begins with example phrases like 'Compare X and Y' and 'X vs Y', clearly indicating the tool's purpose. It states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' This specific verb+resource description distinguishes it from siblings like entity_profile (single entity lookup).

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides example use cases (comparing, ranking, head-to-head). It does not explicitly list when not to use, but the context is clear enough to guide the agent.

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

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

Annotations already mark the tool as read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral context beyond that: account/auth requirements, paid tier for 'thorough', latency expectations, gap reporting behavior, parallel routing, citation resolvability, contradiction scanning, and semantic excerpting. No contradictions with the annotations.

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

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

The description is long but dense with genuinely useful invocation details—auth, alternatives, behavior, depth semantics, and latency. Some minor disfluencies and an awkward 'Also search_within... Need not.' phrase slightly mar the structure, but overall it is well-organized and front-loaded with the most critical constraint (ACCOUNT REQUIRED).

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 no output schema, the description covers everything an agent needs: parameters, depth behaviors, auth prerequisites, fallback tools, output packet contents, gaps, citations, contradictions, and approximate timing. Nothing essential for invoking it correctly 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?

The schema already documents both parameters at 100% coverage, and the description adds significant extra meaning: what 'depth' levels actually do in terms of hops, gap recovery, contradictions, and cost, plus how the question parameter should be phrased as a natural-language broad/multi-part query. This goes well beyond the schema alone.

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

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

The description clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, decomposes questions into facets, and returns a findings packet. It also explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx and search_within, so an agent can select it with confidence.

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

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

Usage guidance is explicit: use this for broad/multi-part questions over structured data, use ask_pipeworx for single lookups or breaking news, and check whether the user is signed in. This gives clear when-to-use and when-not-to-use direction relative to alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds important behavioral details: returns top-N relevant tools with full input schemas and curated examples, ready to call without a second lookup. 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 and well-structured: it states the purpose upfront, lists domains, explains the return format, and gives usage guidance. Every sentence adds value without redundancy.

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

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

Given no output schema, the description adequately explains the return value (top-N tools with names, descriptions, schemas, examples) and usage context. It could mention default limit (20) but the schema does, so completeness is high.

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

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

The input schema covers 100% of parameters with descriptions for each, including aliases. The description lists the same aliases, which adds minimal value beyond the schema. However, the schema includes example values, so the description's contribution is limited.

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 specifies 'Find tools by describing the data or task' and lists concrete domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that either provide direct answers or perform other actions.

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),' giving strong usage context. It does not include explicit when-not-to-use scenarios, but the directive is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds operational context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), soft-fails for patents, and returns specific fields like recent_filings with 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?

Description is fairly long but well-structured: starts with example queries, then primary purpose, then details of sources and return fields, then caveat about name resolution. Every sentence adds value, though could be slightly tighter.

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 lists all return fields (cik, recent_filings, fundamentals, patents, news, LEI). Covers data sources, fallback behavior, and prerequisites. Fully adequate for a read-only info tool with rich annotations.

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

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

Schema coverage is 100%, baseline 3. Description adds nuance: value must be ticker or zero-padded CIK, names not supported. Also clarifies type is only 'company' for now. Provides usage examples and constraints beyond schema.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call'. It uses specific verbs ('research', 'brief me', 'profile') and distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name 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 tells when to use: when user asks for a 'holistic view'. Also tells when not to use: if only a name is provided, instructs to use resolve_entity first. Mentions that patents part may fail after May 2025, setting expectations.

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 denote destructive and idempotent; description adds usage context but not deeper behavioral details like permanence or cascading effects.

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

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

Two sentences, front-loaded with action, minimal waste.

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

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

Covers purpose, usage, and pairing; lacks error handling or behavior on missing key, but sufficient for a simple 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 description covers key parameter fully; description reiterates but adds no new semantics.

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

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

Clearly states it deletes a memory by key, and with siblings 'remember' and 'recall', its role is distinct.

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

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

Explicitly describes when to use (stale context, task done, clear sensitive data) and pairs with related tools.

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

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

Annotations already declare safe read-only, idempotent, non-destructive behavior. The description adds process details (fetches page, extracts title/description/links, emits markdown) and output format (single text blob for site-root/llms.txt), which goes beyond annotations without contradicting them.

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

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

Extremely concise: two sentences and a bullet list. Front-loaded with core purpose. Every sentence adds value with no repetition or fluff.

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

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

Given low complexity (2 params, no output schema, no nested objects), the description fully covers what the tool does, what it produces, and where to use the output. No gaps for an agent to invoke correctly.

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

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

Schema coverage is 100%, so schema already documents both parameters well. The description does not add new semantic information beyond what is in the schema, meeting the baseline expectation.

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

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

Clearly states it generates an llms.txt file for any URL, specifically for AI crawlers. The verb 'generate' matches the tool name, and the resource is well-defined. Among siblings, no other tool has similar functionality, so it distinguishes itself.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor. Provides context for when to use, but does not mention when not to use 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?

Annotations already declare readOnly, idempotent, non-destructive. The description adds specific return content (fields, geometry type, count, capabilities), providing full transparency. 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?

Single sentence, front-loaded with the verb 'Get' and resource, compact and efficient. 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?

For a single-parameter tool with comprehensive annotations, the description covers all essential outputs (fields, geometry type, count, capabilities). No output schema needed as description 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 coverage is 100% with a clear description of the 'url' parameter. The tool description does not add extra parameter details beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves schema info (fields, geometry type, record count, capabilities) from a layer URL. It uses specific verbs and resources, distinguishing it from sibling tools like 'query_layer' which likely query 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?

Usage is implied from the description: use to get metadata. However, no explicit guidance on when to use vs alternatives (e.g., 'query_layer') or when not to use. The context suggests differentiation but lacks explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, confirming safe behavior. The description adds value by listing the exact return fields and clarifying that only active subscriptions are returned by default, with an optional include_inactive parameter. No contradictions.

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

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

Two sentences, no wasted words. The first sentence defines the action and output; the second provides usage context. Well-structured and front-loaded.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It explains purpose, return fields, default filter (active), and practical use cases (review, find id to cancel). Nothing essential is missing.

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

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

Schema coverage is 100% with a clear description for the single optional parameter 'include_inactive'. The description does not add any new meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clearly states the verb 'List' and resource 'the caller's active subscriptions'. Specifies the exact return fields (id, type, params, etc.), distinguishing it from siblings like subscribe/unsubscribe which modify 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?

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel'. This provides clear context and alternative behaviors, implicitly contrasting with subscribe/unsubscribe.

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

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

Annotations provide only basic hints, so the description adds substantial context: the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), and operational impact ('team reads digests daily... affects roadmap'). No contradiction with annotations.

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

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

The description is long but every sentence earns its place—purpose, usage, exclusions, mechanics, rate limits, and cost. It is front-loaded with the most important information and flows logically from what to why to how. No redundancy or filler.

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

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

With 4 parameters, a nested context object, and no output schema, the description covers all necessary ground: invocation conditions, parameter semantics, return behavior (claim_token for status checks), and constraints (rate limit, free). The absence of an explicit output schema is mitigated by describing the token-based response.

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

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

Despite 100% schema coverage, the description enriches parameter meaning: it explains how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), guides message content ('don't paste the end-user's prompt'), and clarifies context usage. This goes well beyond the schema's baseline.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates feedback types (bug, feature, data_gap, praise), differentiating from sibling tools like ask_pipeworx and discover_tools. This is a specific, well-scoped purpose.

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

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

Provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data...') and when-not-to-use exclusions ('if the tool came from a different MCP server... file it with that server instead'). It also gives alternative actions and clarification for ambiguous cases. 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 read-only, idempotent, non-destructive. The description adds caching details (5min-1h), data source (CF analytics-engine), and privacy (no PII). No contradictions with annotations.

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

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

Five sentences with clear front-loading: first sentence states core functionality, then bullet-pointed use cases, followed by data source and caching info. 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?

Tool has low complexity (one optional param, no nested objects). Description covers purpose, return items, windows, caching, and privacy. Without an output schema, it could specify the exact structure of the returned top tools/packs list, but the current detail is sufficient for an agent to interpret the response.

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 for the single parameter 'window' with enum and description. The description adds value by explaining the trade-off between short and long windows ('surfaces what's hot right now vs steady-state demand'), which goes 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 returns top tools, top packs, and total call volume over time windows. It specifies the verb 'returns' and the resource 'what other AI agents are calling on Pipeworx'. This distinguishes it from siblings like 'ask_pipeworx' or 'discover_tools'.

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

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

Three explicit use cases are given (discovering hot data sources, confirming canonical tool, aligning with common needs). It does not include when not to use it or alternatives, but the context is sufficient given the sibling tool list.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds substantial behavioral context: semantic anchor for cross-event pairing, partition filter logic, fill check mechanics, and response structure. 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 quite long but well-structured with clear sections for each mode. Every sentence adds value, though slightly more verbose than necessary. Front-loads the core purpose and alternatives well.

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

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

Given the complexity of the tool (multiple modes, fill check, semantic anchor) and lack of output schema, the description comprehensively explains the response structure and all key behaviors. An agent has sufficient information to select and invoke correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond parameter names. It explains what each parameter does, provides example values, describes the different modes and their outputs, and clarifies recommended usage.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and details their specific functions. This differentiation is crucial given sibling tools like polymarket_edges and polymarket_edge_tracker.

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 guides the agent: 'Call with NO args for a trending_scan', recommends event mode for specific markets, and topic for cross-event scanning. Also warns against trading when fill check shows non-realizable edge, providing clear when-not situations.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context beyond annotations: detailed model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation with slippage and Kelly sizing, caching behavior (1h KV cache keyed on knobs), and diagnostic outputs. No contradictions with annotations.

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

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

The description is very detailed and well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). However, it is quite verbose, containing many specific numeric thresholds and technical details that could be trimmed for conciseness. While informative, it sacrifices brevity.

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 (9 parameters, no output schema), the description is remarkably complete. It explains the response structure (top-level by_segment, fed_candidates, _diagnostics), every field in the opportunities (edge_pp_net, kelly_fraction, market stats, 24h move warning), and the role of each knob. No significant gaps for an agent 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% (all 9 parameters documented in input schema). The description adds meaningful context for many parameters, such as explaining min_liquidity and max_spread_pp as 'Tradeable-edge filters' and detailing min_partition_leg_kelly's role. This adds value beyond the schema descriptions, justifying a 4.

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

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

The description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and explicitly says it is 'Built for 'what should I bet on today''. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by highlighting its three-model-family approach and focus on Pipeworx-based edge detection.

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

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

The description gives explicit guidance on when to use the tool ('discover opportunities without paging hundreds of markets') and includes constraints like Fed bets being excluded and Knobs for filtering. However, it does not directly compare to sibling tools or state when NOT to use this tool in favor of an alternative, which keeps it from a top score.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant detail: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), computation of trend and decay, and limitations (60-day TTL, daily closes, not intraday). 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 verbose but every sentence contributes meaning. It front-loads the core question and provides structured return fields. Could be slightly more concise, 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?

With no output schema, the description fully explains the response format (tracked[], expired[], snapshot_dates[]) with field details. It also covers limits (60-day TTL, snapshot start) and computation nuances. Complete for a complex telemetry 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 value by clarifying default and max for days, and explaining the meaning of window families ('1wk'). It also gives a concrete example of window values, aiding understanding 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: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It explicitly answers the key question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on historical behavior rather than raw edges.

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

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

The description provides clear context on when to use the tool: to differentiate between fresh and persistent edges. It implies usage for historical trend analysis but does not explicitly state when not to use or name alternatives. The sibling tool list gives context but description lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context like walking the ladder, returning verdicts (clean/degraded/cannot_fill), and warning about forced directional risk from partial fills. No contradiction.

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

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

The description is lengthy but well-structured with bold headings for SINGLE-MARKET and BASKET modes. It is efficient given the complexity of the tool, though could be slightly more concise with bullet points.

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

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

No output schema is provided, so the description must and does thoroughly explain return values for both modes, including detailed fields like top_of_book, vwap_fill_price, slippage_pp, and per-leg fill detail. It also covers risk scenarios.

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. The description adds value by explaining default behavior for side in basket mode and different interpretations of size_usd for single-market vs basket, plus clamping limits.

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

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

The description clearly states that the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It details both single-market and basket modes with specific actions and return values, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the risks of not using it, such as thin books and partial fills converting arb into directional positions.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false. The description goes far beyond by detailing compatibility_warning with two distinct cases, temporal_alignment, skipped_cross_type/subtype counters, and when spreads are meaningless. 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 dense but well-structured, front-loading the main purpose and then detailing modes, response fields, and safety warnings. Every sentence adds value, though some sections (e.g., skipped counters) could be slightly more streamlined.

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

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

Given the complexity of the tool and absence of an output schema, the description fully covers the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It ensures an agent understands the rich output without needing 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 proper descriptions. The description adds value by listing the 10 pre-mapped topics for the topic parameter and providing examples for explicit parameters. It clarifies the relationship between topic and explicit modes, aiding parameter selection.

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 computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage which focus on internal markets. Two modes are explicitly defined, adding specificity.

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

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

The description explains when to use each mode (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics currently return compatibility_warnings, advising against assuming tradeability. However, it does not explicitly name alternative tools for cases where this tool is unsuitable.

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, destructiveHint, covering safety. Description adds that it returns attribute rows and geometry, and mentions defaults, but does not detail auth needs or rate limits.

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

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

Two concise sentences with an example hint. No waste, every sentence adds value: states purpose, key parameters, and a usage tip.

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, description mentions returns 'attribute rows (and geometry)' which is adequate for a query tool. Lacks details on pagination or error handling, but overall sufficient given annotations and schema coverage.

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

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

Schema coverage is 100% with each parameter described. The description reinforces SQL-like nature and gives example usage, but adds limited additional meaning beyond schema descriptions.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, specifying SQL-like parameters. It distinguishes from siblings like search_datasets (for discovery) and layer_info (for metadata) by focusing on data retrieval.

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 hints like using where='1=1' and out_fields='*' for sampling, but does not explicitly state when to use this tool over siblings. The context implies after finding a layer via search_datasets, this tool queries its data.

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 beyond annotations: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and behavior when key omitted. Annotations already indicate read-only and idempotent; description confirms and adds scope info. No contradictions.

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

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

Three sentences, front-loaded with action, no wasted words. 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?

Given low complexity (1 param, no output schema), description covers purpose, usage guidance, behavioral scope, and pairing with siblings. Fully sufficient for an agent.

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

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

Only one parameter with 100% schema coverage. Description repeats schema info ('omit to list all keys') and adds context about origin ('previously saved via remember'). Meets baseline for well-covered schema but adds minor value.

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

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

Description uses specific verbs 'retrieve' and 'list' with clear resource 'value previously saved via remember' and 'all saved keys'. Distinguishes from sibling tools 'remember' and 'forget'.

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

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

Explicitly describes when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Provides examples of use cases. Mentions pairing with remember/forget but does not explicitly state when not to use.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details beyond annotations, such as the effect of setting 'mark_read:true' to update read status for subsequent calls, and the format of returned data. No annotation contradiction.

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

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

The description is concise (4 sentences) with no wasted words. The first sentence immediately states the main purpose, followed by details on return values and filtering options. It is well-structured and front-loaded.

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

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

Given no output schema, the description adequately outlines the returned fields (source, citation_uri, raw payload). It covers the 5 optional parameters and their effects. One minor gap: it doesn't specify how 'limit' interacts with 'mark_read', but overall it is sufficiently complete for a simple retrieval tool.

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

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

All 5 parameters have descriptions in the schema (100% coverage), but the description adds context beyond the schema: it explains that 'mark_read' flags events as read to affect future calls, and that 'since' is an ISO timestamp. This enhances understanding of parameter interactions.

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') and clearly identifies the resource ('subscription feed'). It details the returned fields (source, citation_uri, raw payload), setting it apart from sibling tools like 'list_subscriptions' or 'recall'.

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

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

The description explicitly states that polling works fine and mentions an alternative endpoint ('GET registry.pipeworx.io/alerts.json') for scripts and dashboards, guiding when to use the tool vs. external access. However, it does not explicitly contrast with sibling tools like 'list_subscriptions' or 'subscribe'.

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 significant context about data sources, fallback logic, parameter formats, response structure, and the patent API sunset issue. No contradiction.

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

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

The description is well-organized with example queries upfront, followed by functional details. While every sentence adds value, it could be slightly more concise without losing clarity.

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

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

Despite having no output schema, the description fully explains the returned structure (changes[] grouped by source, total_changes count, citation URIs). It also addresses edge cases (patent soft-fail, fallback) and provides clear usage guidance. Highly complete.

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

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

Schema description coverage is 100%, but the description adds extra meaning: relative date formats like '7d', '3m', '1y', typical monitoring window '30d' or '1m', and that 'value' accepts ticker or CIK. This goes 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 a change feed for a company in a time window, covering SEC filings, news, and patents. It uses specific verbs and resources, and distinguishes from the sibling tool 'entity_profile'.

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

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

The description explicitly provides example queries, explains when to use this tool versus 'entity_profile', and outlines fallback behavior (GDELT→GNews) and limitations (patent soft-fail).

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

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

The description adds significant behavioral context beyond annotations: key-value scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. It also clarifies that the operation is idempotent (overwriting same key) and not destructive, consistent with annotations.

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

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

The description is four concise sentences, each adding value. It is front-loaded with the core purpose, then provides usage guidance, behavioral details, and paired tools. 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?

The description is complete for a simple key-value store with no output schema. It explains persistence, scoping, and pairing with recall/forget. It could mention the return value (likely confirmation or the stored value) but is sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds usage examples (e.g., keys like 'subject_property', values as text) but does not provide additional semantic meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the action ('save'), resource ('data'), and scope ('across this conversation or across sessions'). It distinguishes from sibling tools like recall and forget.

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

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

The description explicitly tells when to use the tool: 'when you discover something worth carrying forward'. It provides concrete examples (resolved ticker, target address, user preference) and pairs with recall/forget for alternative actions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it cascades through multiple endpoints, degrades gracefully (if GLEIF/OpenFIGI are unavailable, EDGAR data still returns), and explicitly states that unresolved identifiers are listed under 'unresolved' rather than omitted. No contradictions.

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

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

The description is longer than average (~150 words) but well-structured: it opens with example queries, then a clear directive, then detailed explanations per type. Every sentence adds value, though some example queries could be trimmed. The front-loading is effective.

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

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

Despite no output schema, the description thoroughly explains what the tool returns: identifiers labelled with source, unresolved identifiers listed, and coverage for company (CIK, ticker, LEI, FIGI) and drug (RxCUI, ingredient). It also covers graceful degradation and edge cases, making the tool's behavior fully predictable.

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 (type, value). The description adds extensive context: for 'type' it explains the two entity types with detailed resolution sources; for 'value' it provides accepted formats (ticker, CIK, ISIN, name for company; brand/generic for drug) and examples. This significantly enhances understanding 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: resolving user-spoken names to canonical/official identifiers. It provides explicit example queries ('What's the ticker for…', 'find the CIK for…') and lists supported types (company, drug). It distinguishes itself from sibling tools like entity_profile and compare_entities by being the go-to for 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?

The description gives a strong usage directive: 'Use FIRST whenever you have a name but need an ID.' This tells the agent when to invoke the tool. However, it does not explicitly mention when not to use it or suggest alternatives for other scenarios, leaving some room for ambiguity.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. This provides valuable context that annotations alone do not cover.

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: two sentences plus a parenthetical use-case example. It is front-loaded with the primary action and purpose. No redundant or unnecessary content.

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 params, no output schema), the description covers process (probes, ranking), output structure (ranked list with fields), and use case. Annotations cover safety. The description is complete for an agent to understand and invoke correctly.

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

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

All parameters have schema descriptions (100% coverage), but the description adds meaning by explaining the first entity is treated as the 'subject' and the rest as competitors, and that models defaults to workers-ai. This goes beyond the schema, clarifying how parameters interact.

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: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (Compare) and the resource (AI visibility). It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on AI visibility and ranking.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"' It implies when to use this tool vs single-entity checks, but does not explicitly state when not to use or name alternatives beyond the implication.

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 mark as readOnly, idempotent, etc. Description adds that partial failures degrade gracefully, bundlephobia can take 5-30s on first measurement, and sources_failed will list if it times out. Also details return structure.

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

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

Description is dense but well-organized; front-loaded with core purpose. Slightly verbose but every sentence adds value.

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

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

Despite no output schema, description lists all return fields (summary, advisories, links, versions). Covers limitations, timing, and partial failure handling. Complete for a composite tool.

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

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

Schema covers 100% of parameters. Description adds that scoped packages like @types/node are accepted for 'package' and that 'version' defaults to latest when omitted.

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 composite check for npm packages combining deps.dev and bundlephobia data, with specific verb+resource. It distinguishes from siblings which are unrelated tools.

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

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

Explicitly says 'Use whenever an agent asks is X safe/popular/small or what does adding lodash cost me'. Also clarifies NPM ecosystem only, with alternatives for other ecosystems mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the return structure (name, summary, record_count, owner/org, url) and downstream guidance, but no additional behavioral traits like rate limits or pagination. This is adequate given the annotation coverage.

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-load the purpose and resource, then provide a concise list of return fields and a usage hint. Every sentence earns its place with no extraneous information.

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

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

Given 3 parameters with 100% schema coverage, no required params, and no output schema, the description provides the necessary output structure and usage guidance. It is complete for an agent to use the tool effectively.

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

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

Schema description coverage is 100% with detailed property descriptions for query, limit, and org_id. The description does not add new parameter semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Search') and resource ('City of Victoria GIS open geospatial datasets'), and lists example categories like parcels and zoning. It distinguishes from sibling tools by mentioning downstream tools (query_layer and layer_info) for further use.

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 that the result includes a Feature Service url to be passed to query_layer or layer_info, providing a clear usage flow. It does not explicitly exclude other sibling tools but gives a strong implicit recommendation.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds embedding model (BGE-base-en), similarity measure (cosine), window size (500-char overlapping), character cap (200K chars) with truncation flag, and output details (offsets, scores). No contradictions.

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

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

The description is a single well-organized paragraph, front-loaded with the core action, then usage guidance, output features, pairing information, and technical details. Every sentence adds value with no fluff.

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

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

Given the tool's complexity (semantic search, pairing with another tool, technical constraints) and absence of output schema, the description fully covers purpose, parameters, usage, behavior, limitations, and related tools. It is complete.

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

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

Schema coverage is 100% with good descriptions for all parameters. The description does not add significant new semantic information beyond the schema; it reinforces purpose but provides no critical extras. 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 performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and output details (passages with offsets and scores). It distinguishes from siblings by 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?

The description explicitly says to use when the record is too big for the prompt and mentions an alternative approach using ask_pipeworx_grounded for grounding. This provides clear when-to-use and alternative guidance.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds significant behavioral context: it creates a mutable subscription, returns an id, details delivery channels (feed, email, SMS, webhook) with constraints (10/day cap, webhook signing secret), and notes the requirement for a Pipeworx OAuth account. No contradictions.

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

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

The description is a single paragraph that front-loads the main purpose. It covers all necessary details without excessive verbosity, though the nested examples make it slightly longer than necessary. Still, it earns its space.

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 subscription types, nested params, delivery channels), the description is comprehensive. It explains each type's params, delivery options, constraints, and important notes (OAuth, phone verification). No output schema exists, but the description explicitly states the return value (subscription id).

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 3 parameters with 100% description coverage. The description adds meaningful examples and constraints for each type-specific params object (e.g., sec_8k items, polymarket_edge topic) and delivery options (webhook signing, SMS verification). This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation.

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

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

The description provides explicit context on when to use the tool (setting up subscriptions for specific types like sec_8k, polymarket_edge, etc.) and mentions requirements (Pipeworx OAuth account, phone verification for SMS). It does not explicitly state when not to use it, but the covered conditions are 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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context: returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. 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 slightly long but front-loaded with common user questions and purpose. Every sentence adds meaningful information, and the structure is clear. A minor trim could improve conciseness without losing value.

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

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

Given the annotations (read-only, idempotent, open-world) and single-parameter schema, the description is fully complete. It explains the return format, parameter behavior, and use cases, leaving no ambiguity despite the lack of an output schema.

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

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

Schema coverage is 100% (one parameter fully described). The description adds value by explaining the optional topic parameter's purpose (focus area) and the effect of omitting it (full spread list), listing example values. This goes beyond the schema's minimal description.

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

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

The description clearly states the tool returns category-bucketed example questions to help users explore Pipeworx capabilities. It lists alternative user intents (e.g., 'give me ideas', 'getting started') and distinguishes itself from siblings as 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?

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do', provides two invocation patterns (no arguments vs. with topic), and mentions learning meta-tools. This gives clear when-to-use guidance versus 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?

Description adds ownership enforcement and deactivation (not deletion) beyond annotations (idempotentHint, destructiveHint). 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?

Two sentences, each adding essential information: action then constraints. 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 1-param tool with annotations and no output schema, description covers purpose, ownership constraint, and deactivation effect. Lacks details on error handling but 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?

Schema covers 100% of parameter descriptions (id is required and described as 'Subscription id (uuid) returned by subscribe'). Description adds minimal extra context about ownership over id.

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 'Cancel a subscription by id' – specific verb and resource. Distinct 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?

Explicitly mentions ownership enforcement (you can only cancel your own subscriptions), which guides proper usage and implies when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond these by explaining the verdict set (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify) and the critical distinction between could_not_verify (verification failed) and unsupported (no source exists). It also details the two processing paths and explicitly warns callers about how to interpret failure, which is high-value 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 dense but every sentence serves a purpose: it opens with natural-language triggers, explains the two routing paths, lists verdicts, and closes with an important usage caveat. The structure is front-loaded and scannable, and despite its length, it contains no fluff or redundant restatements of the tool's name or annotations.

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 that there is no output schema, the description thoroughly covers return values (verdict, actual value, citation, reasoning) and failure modes. It also explains the verification pipeline and the difference between could_not_verify and unsupported, which is essential for correct use. For a tool with this complexity, the description is remarkably complete—it leaves no critical ambiguity about behavior or consequences.

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 describes both parameters with examples, and coverage is 100%, so the baseline is 3. The description adds extra semantic value for tolerance_pct, explaining that it overrides the tolerance implied by claim wording and suggesting values (1–2) for hallucination detection. It also provides realistic example claims that clarify the expected format. This goes beyond simple repetition of schema text.

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

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

The description clearly identifies the tool as a fact-checker for natural-language claims, with specific verb ('validate') and resource ('claim'). It distinguishes itself from siblings by explicitly framing it as a unified replacement for multiple sequential calls and by describing its dual routing (SEC EDGAR/XBRL vs. grounded pipeline). The examples of query patterns make its scope unambiguous.

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

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

The description states precisely when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives concrete guidance on how different claim types are handled. However, it does not explicitly mention when NOT to use it or name alternative sibling tools (e.g., ask_pipeworx_grounded), so it lacks the full 'when-not/alternatives' clarity of a 5.

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