Arcgis Sanjoaquin

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing cost implications (free Workers AI vs. BYO Anthropic key) and return structure, without contradiction.

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

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

Two sentences, front-loaded with key action, zero fluff. Every phrase 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, the description details return structure (per-model score, confidence, signals, raw_response + combined view). It fully explains all parameters and optional fields.

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 3. The description enhances by explaining the models array options, _apiKey necessity, and context disambiguation, adding meaning beyond schema.

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

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

The description specifies the exact verb ('probe'), resource ('LLMs'), and output ('score visibility 0-100 per model'). It clearly distinguishes from siblings by targeting AI-marketing audits and brand visibility checks.

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

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

Explicit use cases are given (pre-launch brand checks, competitive monitoring) and details about default model and optional API key. However, it does not explicitly state when not to use or compare to alternatives like 'scan_competitor_ai_presence'.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds meaningful context about routing to other tools, filling arguments, and returning citation URIs. It doesn't contradict annotations.

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

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

The description is long but front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH', 'START HERE'). Each section earns its place, though the list of domains and examples could be slightly trimmed without loss of essential meaning.

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

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

Complex meta-tool with no output schema, but the description explains return format (structured answer with citation URIs), routing behavior, and tier compatibility. It covers the essential contextual needs for an agent to select and 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%, so baseline is 3. The description adds examples and context about what kinds of questions are appropriate, but the schema already describes the 'question' parameter as natural language. No additional parameter syntax or constraints are needed.

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

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

The description clearly states this is a routing tool for factual questions, specifying a verb (ask) and resource (Pipeworx's 5,462 tools/1,419 sources). It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by describing its role as the default entry point.

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

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

The description explicitly says to prefer this over web search, provides trigger phrases ('what is', 'look up', 'find', etc.), and gives concrete alternatives for when to use ask_pipeworx_grounded or deep_research. This gives clear when-to-use and when-not-to-use guidance.

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

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

Beyond the read-only/idempotent annotations, the description reveals that candidate routing improvements are enabled live when under test, that currently none are active so it exactly matches ask_pipeworx, and that it's a full working router with no fallback. This is genuinely useful behavioral context about the beta nature.

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, each carrying information: beta status, current behavior, usage direction, and caveat. It's dense but not wasteful; the redundancy of 'identical universal router' with the parenthetical is slight but acceptable.

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

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

Given the tool's complexity as a router with many potential behaviors, the description adequately covers the beta status, current equivalence to ask_pipeworx, and experimental purpose. It doesn't detail the response shape, but the tool has no output schema and the description explicitly references ask_pipeworx's shape, which is sufficient in context.

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

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

Schema covers all parameters with detailed alias descriptions for question, so schema_description_coverage is 100%. The description adds no additional parameter semantics beyond mentioning 'same arguments' as ask_pipeworx, which is consistent but not additive; baseline 3 is appropriate.

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

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

Description clearly states it's a beta version of ask_pipeworx, an identical universal router with same tools/arguments/response shape, and explains its experimental purpose with candidate routing improvements. It distinguishes from the stable ask_pipeworx sibling by explicitly branding it as the experimental edge.

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

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

Description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router to decide merges. This provides clear when-to-use guidance and implicitly contrasts with the stable ask_pipeworx, though it doesn't explicitly say when not to use it.

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

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

The description reveals behavioral traits well beyond the annotations: it details the exact return shape (answer, evidence, confidence, source, fetched_at, refusal_reason), enumerates all refusal reasons, and discloses the cost of one extra LLM call. This gives the agent a clear mental model of side effects and failure modes, complementing the readOnly/openWorld/idempotent hints without contradiction.

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

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

The description is front-loaded with the core purpose, then systematically reveals mechanism, output format, refusal conditions, use cases, and cost tradeoff. Though lengthy, every sentence adds distinct value—there is no filler or redundancy, making it a model of information-dense yet readable structure.

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

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

With no output schema, the description correctly takes on the burden of explaining return values, including the refusal contract. It also covers routing complexity (5,462 tools), argument filling, and the distinction from the non-grounded sibling, making the tool fully operable in context. Nothing critical is left unspecified.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the natural-language 'question.' The description reinforces that the tool accepts a natural language question, but adds no new parameter-level detail beyond the schema. Baseline of 3 applies because the schema fully carries the semantic load.

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 specific verb phrase: 'Hallucination-resistant answer mode for high-stakes reads,' which clearly identifies the tool's function. It distinguishes itself from the sibling tool ask_pipeworx by emphasizing grounded extraction and refusal behavior, making the purpose unmistakable.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' followed by concrete examples. It also explicitly names the alternative for casual lookups ('prefer ask_pipeworx for casual lookups') and notes the tradeoff of an extra LLM call.

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, and non-destructive. The description goes far beyond by detailing fan-out behavior, resolution confidence handling, closed-market handling, spread warnings, resolution-rule risk, and response shapes. There is no contradiction with annotations, and the behavioral detail is exceptional.

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 section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and examples. Every sentence adds value, but some sentences could be more concise. Overall, it is as brief as possible given the complexity.

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

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

Given the tool's complexity (classifiers, fan-out, response shapes) and lack of output schema, the description provides exhaustive detail on return values, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety behaviors. Nothing essential is omitted.

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%, yet the description adds significant meaning: it explains that 'market' accepts slugs, URLs, or question text; 'depth' maps to quick/thorough; and 'include_raw' controls summary vs full payloads. This enriches the schema definitions considerably.

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 a specific verb 'Research' and resource 'Polymarket bet', and uniquely distinguishes this tool from its many siblings by detailing its exact function: pulling Pipeworx data for Polymarket bets with multiple input types. It leaves no ambiguity about what the tool 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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which provides clear context. However, it does not mention when not to use this tool versus alternatives like polymarket_edges or polymarket_arbitrage, which would improve the 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?

Beyond annotations (readOnly, idempotent, etc.), description explains data sources (SEC EDGAR for companies, FAERS for drugs), fiscal year handling, sorting behavior, and citation URIs. All non-obvious traits disclosed.

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 paragraph, front-loaded with example queries, efficient explanation of two entity types and key behaviors. 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?

Covers both entity types, data sources, sorting, and citations. Without output schema, description explains return structure ('paired data + citation URIs') but could be more explicit about the exact fields returned for each entity type.

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 enum and array types; description adds concrete examples (tickers, drug names), constraints (max 5, min 2), and explains how values affect sorting and scope. Adds meaningful extra guidance.

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

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

The description clearly states 'side-by-side comparison of 2–5 companies or drugs' and gives example queries. It distinguishes from sequential single-pack lookups, which are common sibling tools.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides numerous query examples that signal when to use this tool versus alternatives.

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

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

The description goes far beyond annotations. It discloses account requirements and paid-tier limitations, return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), gap handling ('explicit gaps[]... never invented'), contradiction detection, semantic excerpting, and time expectations. It also clarifies that it is not open-web search, mitigating a likely wrong assumption. Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with this behavior, so 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 long, but appropriately so for a complex tool. It is front-loaded with critical account prerequisites and alternative tool routing, then covers purpose, mechanics, output, and edge cases. While dense, every sentence provides actionable information; however, it could be better organized with paragraph breaks or bullet points for scannability.

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, the description is remarkably complete. It covers prerequisites, exact usage scenarios, alternatives, depth semantics, output structure, gap handling, citation resolvability, excerpting strategy, and latency expectations. With no output schema, the description fully carries the burden of explaining return values and behavior, and it does so thoroughly.

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

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

Schema coverage is 100%, and both parameters have descriptions in the schema. The description adds value by elaborating on the depth parameter's practical effects (e.g., 'standard=5... adds a gap-recovery hop', 'thorough... chases leads', and 'up to ~90s' timing) and explaining that the question can be broad/multi-part. This supplements the schema rather than merely repeating it.

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 primary function: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call'. It uses a specific verb ('research'), identifies the resource (structured data sources), and distinguishes itself from siblings by noting it is 'NOT open-web search' and decomposes questions into facets routed to 5,462 tools in parallel.

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

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

Explicit when-to-use and when-not-to-use guidance is provided: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and specifically for breaking/current-news topics 'prefer ask_pipeworx—it routes to live news APIs'. It even gives an account-based alternative: 'If you are not signed in, use ask_pipeworx instead'.

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

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

The description adds context beyond annotations by explaining that the returned results include names, descriptions, full input schemas, and curated examples. It does not contradict the readOnlyHint, idempotentHint, or destructiveHint annotations. While it doesn't detail side effects, the annotations adequately cover the safety profile.

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

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

The description is front-loaded with the core purpose and then lists domains. It is somewhat long but every sentence adds value, explaining the tool's output and the recommended usage scenario. It is appropriately structured and not overly verbose given the tool's complexity.

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

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

The description covers the tool's purpose, when to use it, and what the output contains. It lacks details about ranking of results (e.g., how 'top-N' is determined) but given no output schema, the description provides sufficient information for an AI agent to select and 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 description coverage is 100%, so the baseline is 3. The description adds examples and explains that 'query' accepts natural language descriptions, but it doesn't add significant new meaning beyond what the schema already provides. It meets the baseline without exceeding it.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous example domains (SEC filings, financials, FDA drugs, etc.) and explicitly distinguishes from siblings by noting it returns top-N tools with full schemas and that it should be called first when many tools are available.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' It provides clear context for when to use, though it does not explicitly state when not to use or list alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description discloses multi-source fan-out, specific return fields, patents soft-fail (USPTO sunset), news fallback (GDELT→GNews), and name unsupported. 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?

Well-structured with examples first, then core behavior, then details. Every sentence adds value, but length could be trimmed slightly. Front-loaded with key purpose, earning a 4 for appropriate size given complexity.

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

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

Given no output schema, description fully details return fields, limitations, fallbacks, and prerequisites. Sibling tools (resolve_entity, compare_entities) provide necessary context for full workflow. Complete 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 descriptions. Description adds context: 'zero-padded CIK', 'only company supported today; person/place coming soon'. Slight but meaningful extra beyond schema, raising from baseline 3 to 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's verb ('profile'), resource ('US public company'), and scope ('full cross-source in ONE parallel call'). It distinguishes from siblings by explicitly preferring over chaining single-pack lookups and directing name-only queries to resolve_entity.

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 ('holistic view'), when-not-to-use ('names not supported – use resolve_entity first'), and alternatives (resolve_entity). Also states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', giving clear priority.

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 destructiveHint=true. Description adds context about clearing sensitive data, reinforcing behavior beyond annotations.

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

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

Two sentences: first states purpose, second gives usage guidelines. No wasted words, 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?

Complete for a simple 1-param tool with annotations. Covers what, when, and pairing. No output schema needed.

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

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

Schema has 100% coverage with clear description of 'key' parameter. Description does not add additional meaning beyond what schema provides.

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

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

The description clearly states the verb 'Delete' and resource 'stored memory by key'. It distinguishes from siblings by implying it is the counterpart to 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task done, or clear sensitive data. Suggests pairing with remember and recall but no explicit alternatives or 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds value by explaining the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' No contradictions with annotations.

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

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

The description is concise with 4 sentences, each adding value: main action, process, use cases. 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?

The description covers purpose, process, output format, and use cases. With 2 parameters and no output schema, it provides sufficient context for an agent to use 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 description coverage is 100%, so baseline is 3. The description does not add additional meaning beyond what the schema already provides (e.g., default and max for max_links).

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

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

The description clearly states the verb 'generate', the specific resource 'llms.txt file for any URL', and distinguishes it from sibling tools by focusing on generating a structured file for AI crawlers. It explicitly mentions the output format and use cases.

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

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

The description provides explicit use cases like 'getting a client's site indexed by AI', 'drafting llms.txt for your own project', and 'auditing how an AI crawler would see a competitor'. However, it does not mention when not to use it or suggest 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, idempotentHint, and destructiveHint false. The description adds specific behavioral detail about the returned schema data (fields, geometry, count, capabilities), which is consistent and beyond the annotation scope. 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?

Single sentence front-loads the action and result; no wasted words. Perfectly concise while conveying all necessary purpose and output 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 one required parameter, no output schema, and comprehensive annotations, the description fully explains what the tool returns (fields, geometry type, count, capabilities). No missing context for correct invocation.

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

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

Schema coverage is 100% for the single 'url' parameter, with a detailed description and example. The tool description itself does not add new parameter semantics beyond confirming the URL type, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as retrieving an ArcGIS layer's schema via URL, specifying exact outputs: fields (name + type), geometry type, record count, and capabilities. It distinguishes itself from potential siblings like query_layer by focusing on schema rather than 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?

The description provides clear usage context (when you need layer schema metadata) but does not explicitly state when to avoid this tool or mention alternatives among siblings. The narrow scope implies its use case, but lacks exclusion 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 safe, read-only behavior. The description adds value by specifying exact return fields and suggesting cancellation use, with no contradiction.

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

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

Two sentences, front-loaded with core purpose, then additional details. Every word is useful.

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

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

Even without an output schema, the description explicitly lists all returned fields, making the tool's output 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% and the parameter is well-documented there. The description adds no extra meaning 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 lists active subscriptions and enumerates returned fields (id, type, params, etc.), distinguishing it from siblings like subscribe/unsubscribe.

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

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

Explicitly provides two use cases: reviewing active subscriptions before adding more and finding an id to cancel, though it lacks explicit when-not-to-use guidance.

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

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

Annotations are all false and provide no safety context, so the description carries the full burden. It discloses rate limiting (5 per identifier per day), the claim_token workflow for reading resolution status, that it's free and doesn't count against quota, and that the team reads digests daily. This is rich behavioral context well beyond the annotations.

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

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

The description is long but front-loaded with the core purpose and each sentence adds operational value: usage triggers, scope exclusions, content guidance, claim_token behavior, rate limits, and quota impact. It could be trimmed slightly, but there is no real 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 four parameters, a nested context object, no output schema, and no useful annotations, the description covers everything an agent needs: when to use, what to include, how to follow up, rate limits, and scope boundaries. It is complete for a feedback 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% and each parameter is already described. The description adds extra value by demonstrating claim_token usage with an example ('pipeworx_feedback({claim_token:"pwfb_…"})') and by advising that message should be framed around Pipeworx tools/packs, not the end-user's prompt. This goes beyond the schema, though not dramatically.

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 specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes feedback from sibling tools like ask_pipeworx by narrowing scope to reporting bugs, feature requests, data gaps, or praise about Pipeworx 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?

It explicitly states when to use ('Use when a tool returns wrong/stale data...'), when not to use ('if the tool came from a different MCP server... file it with that server instead'), and provides an alternative. It also instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: self-aggregating from CF analytics-engine, no PII, cached 5min-1h. 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 paragraphs, all adding value, front-loaded with main purpose. Could be slightly more compact but no redundancy.

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

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

Given no output schema, description adequately explains return structure (top tools, packs, call volume). Caching and data source are disclosed. Complete for a simple read-only 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 the single parameter 100% with enum. Description adds meaning: default value and behavior differences between windows, which is valuable 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 a window (24h,7d,30d). It uses specific verbs ('returns') and resources, distinguishing it from sibling tools like discover_tools or search_datasets.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning use case with demand). Guidance on window choice ('shorter windows surface what's hot right now; longer windows show steady-state demand') is excellent.

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 extensive behavioral context: walks child markets, checks date-axis ordering, partition sum check with deviation threshold, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against live CLOB depth, and warning when realizable edge ≤ 0. 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 lengthy but well-structured with front-loaded purpose and mode distinctions. Each paragraph adds value, though some technical details (Jaccard threshold, fill check mechanics) could be condensed. Clear organization with logical flow.

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

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

Despite no output schema, the description explains response structure (opportunities[] with gap_pp, suggested_trade, reasoning, partition_check details). Covers edge cases like placeholder slugs, fill check, and when not to trade. Complete for an arbitrage detection tool.

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

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

Schema coverage is 100% with clear descriptions. The description enriches further by explaining expected input format (slugs or URLs for event, seed questions for topic) and the behavior of each mode, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'. It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode: no args for trending scan, event for specific market, topic for cross-event scan. Recommends event mode for specific markets and notes cross-event mode catches patterns missed by single-event. Also advises using polymarket_fill_risk for custom sizing.

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

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

Discloses many behavioral details: caching at KV level for 1h, response structure (by_segment, diagnostics, fed_candidates), edge calculation, slippage handling, and knob effects. Annotations already mark it as read-only and idempotent, and description adds rich context without contradiction.

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

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

Description is very long and includes extensive detail on model families (crypto_price, news_momentum, etc.) that may be excessive for an agent. However, it is well-structured with clear sections and front-loaded purpose. Could be more concise.

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

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

Given the complexity (9 params, no output schema, nested logic), the description covers all essential aspects: output structure, caching, filtering knobs, diagnostics, and edge calculation. Missing only explicit return type reference, but high completeness overall.

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%, yet description adds significant value by explaining each parameter's purpose, defaults, and interactions (e.g., min_partition_leg_kelly vs min_kelly, slippage_pp assumptions). Goes well beyond bare schema descriptions.

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

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

Clearly states main action: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes this tool from siblings like polymarket_arbitrage by focusing on Pipeworx-specific edge detection. However, it does not explicitly contrast with all sibling tools, so not a perfect 5.

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

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

Provides clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' Implicitly advises when to use, but lacks explicit 'when not to use' or alternative recommendations. Still strong 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 behavior. The description adds valuable context: history bounded by 60-day TTL, snapshots on cache-miss, decay computed from daily closes (not intraday), and detailed 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 dense but appropriately front-loaded with purpose. Each sentence adds value, covering inputs, response structure, and limitations. Slightly lengthy but justified by no output schema.

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

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

Given the complexity (2 optional params, no output schema), the description covers inputs, response fields, behavioral notes (TTL, gaps, decay computation), and limitations. Highly complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with full descriptions for both parameters. The description restates defaults and ranges but does not add significant new meaning beyond the schema. 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 clearly states the tool provides 'edge persistence and decay telemetry' and answers 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling polymarket_edges by focusing on time-series analysis of edge persistence.

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

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

The description explicitly contrasts a fresh wide edge versus a 3-week-old wide edge to illustrate when to use the tool. It does not list alternative sibling tools or explicitly state when not to use it, but the context is clear.

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

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

The description adds significant behavioral context beyond annotations: it walks the order book ladder, returns verdicts like 'clean|degraded|cannot_fill', and highlights risks like forced_directional_risk. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which are consistent with the description's non-destructive, read-only nature.

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

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

The description is relatively concise given the complexity of two modes and multiple return fields. It front-loads the core purpose and uses capitalization for emphasis. However, it could be slightly more streamlined, as some sentences are dense.

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

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

Given the lack of an output schema, the description thoroughly explains return values for both modes, including top_of_book, vwap_fill_price, slippage, verdict, theoretical vs realizable sums, and risk warnings. It covers parameter defaults, modes, and edge cases, making it highly complete.

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

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

Schema coverage is 100% with descriptions. The description adds nuance: for `side` it explains auto-detection in basket mode ('default auto from partition sum'), and for `size_usd` it clarifies interpretation as 'shares per leg' in basket mode. This 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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, specifies the return fields, and provides context on when to use it, differentiating it from sibling tools 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 states '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 theoretical overround not being capturable and partial basket fills converting an arb into an unhedged directional position.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds extensive behavioral details: two modes, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). Explains edge cases and limitations far beyond annotations.

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

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

Well-structured: starts with purpose, then modes, response details, safety fields. Every sentence adds value, though some technical details (e.g., skipped_cross_type/subtype counters) could be slightly more concise. Overall front-loaded and efficient.

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

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

Given complexity and no output schema, description adequately explains return values (leg-by-leg prices, top_spreads_pp) and safety fields (compatibility_warning, temporal_alignment). Missing explicit output format, but sufficient for agent understanding.

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

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

Schema coverage is 100% with descriptions and examples. Description adds functional context for 'topic' (lists the 10 shortcuts) and explains that explicit params override topic-mapped sides. Adds value beyond schema by describing interplay.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on cross-venue comparison and describes two modes (topic and explicit).

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

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

Explicit guidance on when to use: comparing prices across venues for the same event. Also explains when not to use via compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events, temporal misalignment). Warns that most pre-mapped topics return warnings, 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns attribute rows and geometry, which is helpful. 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 two sentences, concise and front-loaded with the core purpose. Every phrase adds value; no wasted words.

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

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

The description covers the tool's purpose, parameters (via schema), return type, and usage hints. Given the annotations and schema, the description is sufficiently complete for an AI agent to invoke correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds interpretive context (e.g., SQL-like where clause examples) and the sampling tip, which 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 queries an ArcGIS Feature/Map Service layer, specifies the source URL from search_datasets, and lists SQL-like parameters. It distinguishes itself from siblings by focusing on ArcGIS layer querying, which no other sibling 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 provides usage tips (e.g., using where='1=1' + out_fields='*' to sample) and explains parameters. However, it does not explicitly state when not to use this tool or list alternatives, though the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds scoping (identifier) and a usage nuance (omit key to list all), adding value beyond annotations.

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

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

The description is concise, well-structured, front-loaded with the action, and every sentence adds value.

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

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

Given the tool's simplicity (one optional param, no output schema) and comprehensive annotations, the description fully covers behavior, scope, and relationships with siblings.

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 'key' parameter. The description reinforces but does not add significant new detail 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 verb (retrieve/list) and resource (saved values/keys), and distinguishes it 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?

It explains when to use (look up stored context) and pairs with remember/forget, but does not explicitly say when not to use it.

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

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

Description claims mark_read:true modifies state by flagging events as read, contradicting the readOnlyHint annotation (true). This is a serious inconsistency that misleads the agent about side 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?

Four sentences, front-loaded with main purpose, no wasted words. Each sentence adds distinct value: purpose, return fields, filtering options, and usage guidance.

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

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

For a tool with no output schema, describes key return fields and behavior (mark_read). Lacks detail on pagination or ordering, but sufficient for an agent to understand basic usage.

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

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

All 5 parameters are fully described in the schema (100% coverage). The description adds valuable usage examples like 'sec_8k' for type and ISO timestamp for since, and explains the mark_read side effect, exceeding 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?

Clearly states verb 'Pull' and resource 'fired events from your subscription feed'. Lists returned fields and distinguishes from siblings like 'list_subscriptions' and 'subscribe' by focusing on events rather than subscription management.

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 polling works fine and provides an alternative REST endpoint for scripts/dashboards, guiding when to use which interface. Does not explicitly exclude any scenarios but provides clear context.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds significant behavioral context: fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO due to API sunset, and return format (grouped changes, total count, citation URIs). No contradictions with annotations.

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

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

Description is a single paragraph but is well-structured and front-loaded with example queries. Every sentence adds value, though it is somewhat dense. Could be slightly more concise but appropriate for the tool's complexity.

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

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

Despite no output schema, description informs that returns 'changes[]' grouped by source, total_changes count, and citation URIs. Covers multiple edge cases (fallback, soft-fail). For a tool with three required parameters and no nested objects, this is sufficiently complete.

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

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

Schema covers all 3 parameters (100% coverage). Description enhances semantics: explains 'since' accepts ISO or relative formats with examples ('7d', '30d', '1y'), suggests '30d' or '1m' for monitoring; clarifies 'value' accepts ticker or CIK; notes 'type' only supports 'company'. Adds value beyond the schema.

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

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

Description clearly states the tool provides a change feed for companies (SEC filings, news, patents) within a time window. Uses example queries to illustrate purpose and explicitly distinguishes from sibling 'entity_profile' for static profiles.

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

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

Provides explicit usage guidance: when to use this tool versus 'entity_profile' for static data. Explains 'since' parameter with examples and suggests default values. However, does not explicitly list when not to use, though the distinction is implied.

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

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

Disclosure of persistence behavior (authenticated users get persistent, anonymous 24h retention) and pairing with recall/forget. Annotations confirm write operation (readOnlyHint=false) and idempotency (idempotentHint=true); 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 core purpose. No redundancy, efficient use of words.

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

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

With two simple parameters, full schema coverage, and annotations, the description is complete. It explains storage scope and duration, and integrates with sibling tools.

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

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

Schema provides 100% coverage with clear parameter descriptions. The description adds examples ('subject_property', 'target_ticker') but does not significantly extend schema information. Baseline 3 is appropriate.

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

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

Description clearly states 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, etc.). It distinguishes from sibling tools like recall and forget by describing the storing function.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. It pairs with recall/forget and gives usage context (scoped by identifier, persistence details).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing internal cascading through multiple lookup endpoints, source systems (SEC EDGAR, RxNorm), and the return of citation URIs. This goes beyond the annotations, though it does not discuss error handling or edge cases such as ambiguous name resolution failures.

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 densely packed but well-organized: it opens with relatable query examples, states the core purpose, then gives structured type-specific details and a closing efficiency note. There is minor redundancy with the schema (e.g., repeating input formats), but every sentence contributes to the agent's decision-making, so it earns its place.

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

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

For a 2-parameter lookup tool with no output schema, the description covers purpose, usage, supported types, return values (including source and citation URI), and internal behavior. It equips an agent with all necessary context to select and invoke the tool correctly, even without an output schema to reference.

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

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

Schema coverage is 100%, providing detailed descriptions for both parameters. The description enhances this by explaining the 'user-spoken' nature of the input, providing concrete examples (AAPL, 0000320193, ozempic), and noting auto-disambiguation. This adds practical meaning beyond the schema's structural definitions.

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

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

The description uses the specific verb 'resolve' and identifies the resource ('user-spoken NAME to canonical/official identifier'). It clearly distinguishes from siblings by stating that other tools require these identifiers as input and by naming the supported entity types (company, drug). Examples of user queries further clarify the 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?

Explicitly instructs 'Use FIRST whenever you have a name but need an ID', which establishes a clear trigger for use. It also explains that the tool replaces 2-3 manual lookups and lists supported input forms, giving the agent a complete usage picture without needing to inspect sibling tools.

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

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

Annotations already indicate safe, read-only behavior. The description adds significant context: it internally probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with score, confidence, and signal density per entity. 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 four sentences, front-loaded with the core action, and each sentence adds value: purpose, mechanism, use case, and return format. 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?

Given no output schema, the description compensates by listing return fields (ranked list, score, confidence, signal density). It covers purpose, input (entities, models, apiKey, context), and process. No obvious gaps for a comparison 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%, but the description adds meaning beyond the schema by noting that the first entity is treated as the 'subject' for narrative and the rest as competitors. This provides crucial context not in the schema.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and clearly states the tool compares AI visibility across multiple entities. It distinguishes from sibling 'ai_visibility_check' by explicitly mentioning it uses that tool internally for multiple entities.

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

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

The description gives a clear use case: 'Useful for competitive AI-marketing audits' with an example question. However, it does not explicitly state when not to use or mention alternatives like 'ai_visibility_check' for single entities, though the sibling list provides that context.

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

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

Annotations already indicate read-only, idempotent, open world. The description adds important behavioral details: partial failures from bundlephobia timeout, listing sources_failed, and that the rest still returns. No contradictions.

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

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

Description is somewhat long (3 sentences) but every sentence provides essential information. Front-loaded with the main purpose. Could be slightly more concise but still 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 clearly enumerates all return fields (summary block, per-advisory detail, links, alternative versions). Covers edge cases like partial failures and context about measurement delays. Complete for the tool's 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 good descriptions. Description adds minor context about defaulting to latest version and accepting scoped packages, but does not significantly exceed what schema provides.

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

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

The description clearly states it performs a composite check for npm packages covering license, advisories, size, and tree-shaking. It distinguishes itself from siblings by being specific to npm and combining deps.dev and bundlephobia.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with the description. The description adds useful context about the scope (San Joaquin County GIS) and return format, beyond what annotations provide. 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 two sentences with no wasted words. It front-loads the purpose and provides specific details about return values and downstream usage.

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

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

Despite no output schema, the description fully explains the return values (name, summary, record_count, owner/org, Feature Service url) and how to use them. The tool has only 3 parameters, all well-documented, and no nested objects.

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 context about the geographic scope (San Joaquin County GIS) and usage examples, which are not in the schema. This adds meaning 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 searches San Joaquin County GIS open geospatial datasets by keyword, listing example dataset types and specifying the returned fields (name, summary, record_count, owner/org, Feature Service url). It also differentiates from siblings by mentioning that the url can be passed to query_layer/layer_info.

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

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

The description implies the usage workflow: search datasets, then use query_layer/layer_info with the returned url. It does not explicitly state when not to use or provide alternatives, but the context is clear and the workflow is well-defined.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds rich context: offset for verification, embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flagging).

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

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

Well-structured with two main sentences plus technical details. No wasted words, but slightly longer due to thoroughness.

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

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

Despite no output schema, description fully explains return value: 'top-N passages with character offsets and similarity scores.' Also covers edge cases (truncation flagging).

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 description adds value: 'max ~200K chars' for text, '1-20, default 5' for limit, and example queries for query parameter.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb (search) and resource (text inside a record). It distinguishes from siblings like ask_pipeworx_grounded by mentioning pairing.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes benefits. Also pairs with ask_pipeworx_grounded, providing an alternative.

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

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

Description says 'Creates a new subscription' implying non-idempotent behavior, but annotation has idempotentHint=true. This is a direct contradiction. While description adds useful delivery constraints (SMS cap, webhook secret once, auto-disable), the idempotency contradiction is critical.

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

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

Description is well-structured: main action first, then types, then delivery options. Every sentence provides necessary detail without fluff. Length is appropriate for complexity.

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

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

Given complexity (3 params, nested objects, 5 enum types, delivery options) and no output schema, description is highly complete. Covers all required info, constraints, and example use cases. Distinguishes from 33+ sibling tools.

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

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

Schema coverage is 100% (baseline 3), but description adds extensive value: explains each 'type' option with usage examples, details 'params' structure with required fields, and describes 'delivery' channels with constraints. Goes far 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 verb ('Create'), resource ('proactive monitoring subscription to a live-data event stream'), and return value ('Returns the new subscription id'). It distinguishes from siblings like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

Explicit when-to-use: setting up monitoring on specific event streams. Lists supported types with examples. Includes prerequisites ('Requires a Pipeworx OAuth account, anonymous + BYO cannot persist'). Implies alternatives like 'recent_alerts' for pulling.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: returns 'category-bucketed example questions' with tool invocation details. No contradictions.

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

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

Description is well-structured, starting with trigger examples, then purpose, return format, and arguments. Every sentence is informative, though slightly verbose. Efficient for its purpose.

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

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

Given no output schema, the description thoroughly explains the return format (category-bucketed examples with tool+argument shape). Complexity is low, and all necessary context is provided.

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

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

Single parameter 'topic' with schema coverage 100%. Description adds value beyond schema by listing example values and explaining that omitting it gives a cross-category spread. However, the schema already has a good 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 it is the onboarding entry point for new agents, returning category-bucketed example questions. It distinguishes itself from sibling tools by positioning it as the first tool to use when the agent does not know what Pipeworx can do.

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

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

Explicitly specifies when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Also explains how to vary input ('Call with no arguments for the full spread, or pass topic') and hints at learning meta-tools. No when-not needed given its onboarding role.

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 behavioral traits beyond annotations, such as 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' It also explains ownership enforcement, which annotations 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?

Two concise sentences, front-loaded with the action. Every sentence adds value with no redundancy or fluff.

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

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

Given one parameter, no output schema, and simple mutation, the description fully explains the effect (deactivation, historical availability) and ownership enforcement, making it complete for agent use.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema for the 'id' parameter; it only repeats that it's returned by subscribe.

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 'Cancel a subscription by id,' a specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by indicating it's the cancellation action.

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 a usage guideline: 'Ownership is enforced — you can only cancel your own subscriptions.' It implies when to use (own subscriptions) but does not explicitly state 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 readOnlyHint=true and idempotentHint=true. The description adds behavioral details: it returns a verdict (with specific allowed values), the actual value with a pipeworx:// citation, and reasoning. It explains the two processing pipelines (structured for financials, grounded for others) and mentions the percent-delta math. 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 front-loaded with example queries and a clear purpose. It has 8 sentences, each adding value. Could be slightly tightened, but it is well-structured and not verbose.

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

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

No output schema exists, so the description must explain return values, which it does (verdict, actual value with citation, reasoning). It covers both processing pipelines and mentions the efficiency gain (replaces 4-6 sequential calls). Missing details on error handling or ambiguous claims, but overall sufficient for a tool with simple parameters.

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% (both parameters described). The description adds significant meaning: it explains tolerance_pct as a control for hallucination detection (overrides implied tolerance, set 1-2 for strictness) and describes the default behavior. The claim parameter's example is clear and contextual.

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 concrete query examples ('Is it true that…', 'fact check', etc.) and explicitly states 'natural-language claim verification against authoritative sources.' It clearly distinguishes between handling of company-financial claims (SEC EDGAR + XBRL) and other factual claims (grounded pipeline), setting it apart from sibling tools like ask_pipeworx.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the fallback routing logic. However, it does not explicitly state when not to use this tool (e.g., for open-ended questions not presented as claims), which would be helpful.

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