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 cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, and the description does not contradict them. It adds useful behavior beyond annotations: the tool routes, fills arguments, and returns structured answers with stable citation URIs. It does not mention latency or cost, but the annotation coverage lowers the burden.

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

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

The description is front-loaded with the key instruction, then gives mechanism, trigger phrases, and examples. It is longer than average because of the domain list and six examples, but all sections are useful. Minor redundancy between 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it' keeps it from a 5.

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 router tool with no output schema, the description covers input, routing behavior, argument filling, output format, citations, and concrete examples. It is slightly incomplete because it does not signal when to prefer sibling tools like ask_pipeworx_grounded or deep_research, nor mention possible cost/latency from fanning out to many sources.

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

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

Schema description coverage is 100%: the schema already fully documents the 'question' parameter and its aliases. The description contributes example questions but no additional parameter-specific semantics, so the baseline of 3 applies.

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

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

The description clearly defines ask_pipeworx as a question router: it 'routes the question to the right one of 5,710 tools across 1494 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is specific and distinguishes it from web search, but it does not explicitly differentiate it from sibling tools like ask_pipeworx_grounded or deep_research, so it stops short of a 5.

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

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

It provides explicit usage triggers: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions.' It also lists example queries and domains. It does not explain when to prefer sibling alternatives such as ask_pipeworx_grounded or deep_research, but the usage context is clear and actionable.

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

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

Annotations already carry the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds genuinely useful context on top: behavior may change live whenever a routing candidate is under test, no candidate is active as of 2026-07-26 so it currently matches the stable router exactly, and calls are compared against the stable router for evalution. This time-varying behavior disclosure is exactly what an agent needs beyond annotations, and there is no contradiction with them.

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

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

Five sentences, roughly 85 words, with identity and scope in the opening sentence and each subsequent sentence earning its place: current state, when to use, evalution purpose, and the fallback clarification. The parenthetical '(same 5,710 tools, same arguments, same response shape)' slightly over-specifies 'identical,' but it reinforces that this is not a degraded stub.

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, but the description closes that gap by stating 'same response shape' as ask_pipeworx. For a tool with time-varying behavior, it covers identity, current state, usage, purpose, and functionality; the only minor gap is not explaining what triggers a candidate going live, which is beyond what an agent needs to call it correctly.

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

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

Schema covverage is 100% — the question param and all five aliases are documented (albeit circularly: 'Alias for question' for the aliases) — so the baseline is 3 and the description need not add param detail. It only says 'same arguments,' a pointer to ask_pipeworx rather than new meaning, which is acceptable given the schema already carries the burden.

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

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

The description states a specific identity — a beta version of ask_pipeworx, an identical universal router over 5,710 tools — in its first sentence, and distinguishes it from the stable sibling by the experimental-edge framing. It could be sharper since it never states the core function in plain verb form ('routes a natural-language question to the best tool'), relying on the term 'universal router' plus the tool name instead.

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

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

Explicit guidance is present: 'Use it exactly like ask_pipeworx when you want the newest routing,' which also implies the exclusion — use the stable router when you don't want experimental behavior. It stops short of naming ask_pipeworx_grounded or stating a hard when-not-to-use rule, but the stable-versus-experimental contrast 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 mark the tool read-only, idempotent, and non-destructive, but the description adds substantial behavioral context: it extracts answers ONLY from what the tool result contains, returns explicit refusal reasons such as not_in_source and no_tool_match, and discloses the extra LLM call cost. There is no contradiction with the annotations.

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

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

The description is dense but well organized: purpose, return contract, refusal contract, then usage guidance. It could trim the specific tool/source counts ('5,710 across 1494 sources'), but overall each sentence earns its place and the critical usage warning is front-loaded.

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

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

For a tool with no output schema, the description fully specifies the return shape, refusal reasons, cost tradeoff, and usage constraints. An agent has everything needed to call it correctly and interpret either a grounded answer or an explicit refusal.

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 input schema already documents all six parameters and their aliases. The description adds no per-parameter meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads,' and explicitly differentiates it from ask_pipeworx by describing the grounded extraction behavior. The success/refusal return contract further clarifies exactly what the tool does, allowing an agent to distinguish it from siblings without opening schemas.

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

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

It states explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete domains like financial verdicts and legal claims. It also gives a clear when-not-to-use: prefer ask_pipeworx for casual lookups because this mode costs 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?

Annotations already declare readOnly=true, idempotent=true, openWorld=true; the description adds substantial context beyond that: parallel decomposition across 5,710 tools, findings-packet return with gaps[] to avoid hallucination, contradiction[] scan, fetchable citation_uri, semantic excerpting, and latency expectations. It also discloses auth/paywall requirements, which is crucial for execution.

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 information-dense; it front-loads the signup requirement and immediate alternative, then flows from core functionality to use cases to depth semantics and output details. Every paragraph carries non-redundant operational information needed to invoke deep_research correctly.

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

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

For a tool with no output schema, the description fully specifies the return shape (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), the gaps[] behavior, the contradictions[] scan for standard/thorough, and timing. It also covers the if-unsigned-in fallback and the paid deep tier, so an agent has everything needed to decide and call.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by explaining that `question` accepts broad/multi-part prompts ('decomposition is the point') and by detailing what each `depth` enum value actually does (quick=single hop, standard=gap-recovery + contradictions, thorough=iterative hop + paid). This goes beyond the schema descriptions.

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

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

The description states a specific verb ('research') and resource ('Pipeworx's 1494 STRUCTURED data sources') and explicitly contrasts with open-web search, distinguishing it from ask_pipeworx. It also names the sibling alternative and the conditions for selecting it, so an agent can tell tools apart without opening schemas.

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

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

Explicitly says 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx'. It defines the best use case as broad/multi-part questions over structured data and enumerates depth tiers with their intended use (quick/standard/thorough), giving clear selection criteria.

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

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

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral details: unclassified legs are never paired, both compatibility_warning and compatibility_codes can be non-empty even when matched_pairs > 0, skipped comparisons are exposed via counters, and temporal_alignment clarifies resolution-period matching. This goes well beyond what the annotations alone communicate.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. It is dense, and some warnings (e.g., pre-mapped ≠ tradeable) are repeated, but the complexity of the tool justifies most of the length.

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

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

With no output schema, the description carries the full burden of explaining the response shape, safety fields, compatibility codes, skipped-pair counters, and alignment semantics. It covers the behavioral edge cases an agent needs to interpret results correctly, making it effectively complete for this complex tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics by explaining that topic shortcuts auto-fetch the matching event on each venue and that explicit ticker/slug parameters enable custom pairings. This supplements the schema's per-parameter descriptions without being redundant.

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

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

The description clearly identifies the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question, and the two modes are explained. It does not use an explicit verb like 'calculate' or 'show', and it does not directly contrast itself with sibling tools such as polymarket_arbitrage, though the resource and scope are unambiguous.

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

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

The description gives strong guidance on when to use topic mode versus explicit ticker/slug mode, and warns that pre-mapped topics are often not tradeable, steering agents toward explicit pairings for real signals. It does not explicitly state when not to use the tool or name alternate tools for other purposes, so it lacks full exclusionary guidance.

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

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

Annotations already 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 indicate a safe read-only, idempotent operation, but the description goes far beyond: it discloses that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, that LEI/FIGI enrichment degrades gracefully if sources are unavailable, that internal cascades through multiple lookup endpoints occur, and that ISIN inputs resolve via GLEIF mapping to the legal entity. This adds substantial context about failure modes and internal behavior that 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?

The description is long but tightly packed with necessary detail for a complex multi-source lookup tool. It front-loads the purpose in the first sentence (after examples), gives an explicit usage directive, and then breaks down behaviors by type. Some redundancy exists (e.g., GLEIF mentioned multiple times), but overall the structure is logical and each sentence earns its place. A 5 would require tighter editing.

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 takes on the responsibility of explaining return behavior: identifiers labelled with source, explicit 'unresolved' field, RxCUI + ingredient + brand for drugs, graceful degradation, and internal cascading. It covers edge cases like non-US issuers and ISIN resolution. This is comprehensive for a tool of this complexity.

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

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

Although the schema already provides 100% coverage for both parameters, the description enriches this significantly. For 'type', it explains the two enum values in depth (company vs drug, what each returns, cross-source identity spine). For 'value', it lists accepted formats (ticker, CIK, ISIN, name) and gives concrete examples for both company and drug. It also clarifies that an ISIN resolves to the legal entity, a nuance not present in the schema.

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

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

The description clearly states the tool's core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists concrete example queries and distinguishes this tool from siblings by explicitly saying 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource pairing that is not a tautology and differentiates from tools like entity_profile.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also clarifies the supported types and input formats, and notes that using this tool 'replaces 2-3 manual lookups.' However, it does not explicitly name alternative sibling tools or state when NOT to use it (e.g., when a full profile is needed), so it falls slightly short of a 5.

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

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

Annotations already 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?

The description discloses valuable behavioral details beyond the annotations: how claims are routed, that verdicts include 'could_not_verify' and 'unsupported' with distinct meanings, that 'could_not_verify' carries a verification_error and is not evidence, and that evidence includes verbatim quotes with pipeworx:// citations. This aligns with the read-only, open-world, idempotent hints and adds rich context.

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

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

While lengthy, every sentence contributes meaningful information: examples, usage triggers, routing logic, return values, caveats, and performance benefits. It is well-organized and front-loaded with examples, making it efficient for an agent to parse.

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 tool is complex with multiple execution paths and nuanced verdicts. The description covers purpose, when to use, behavioral expectations, parameter nuances, return format, error semantics, and performance trade-offs. With no output schema, this description stands in for it sufficiently, making the tool fully understandable.

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?

Even though schema coverage is 100%, the description adds significant meaning: tolerance_pct overrides the implied tolerance, defaults to the implied wording capped at 5, and is recommended at 1–2 for hallucination detection. This goes well beyond the raw schema descriptions.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, with specific verb phrases like 'fact check' and 'verify the claim that...'. It also distinguishes its dual fast-path/grounded-pipeline behavior from sibling tools, making its purpose unambiguous.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates company-financial claims (SEC EDGAR/XBRL path) from any other claim (grounded pipeline), and provides practical guidance on tolerance_pct for hallucination detection.

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