Arcgis Southbend

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

Discloses return structure (score, confidence, signals, raw_response) and explains that Anthropic requires a BYO API key. Annotations already confirm safety (readOnlyHint, idempotentHint), so description adds valuable behavioral context.

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

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

Three sentences, front-loaded with purpose, no redundant words. Each sentence adds unique value: function, API key detail, return format and use cases.

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 outlines the return format and use cases. It could mention error handling but is otherwise comprehensive for a safe, read-only tool with 4 parameters.

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

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

Schema covers all parameters with descriptions (100% coverage). The description adds context like default model, pricing note, and guidance on when to use _apiKey, enhancing understanding beyond schema.

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

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

The description clearly states that the tool probes LLMs to score visibility, specifying the verb 'probe' and resource 'LLMs'. It distinguishes from sibling tools by focusing on visibility scoring and default model details.

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

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

Explicitly mentions use cases like AI-marketing audits and pre-launch brand checks. Lacks formal exclusion criteria but provides clear context and optional parameter usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description adds valuable behavioral context: it routes to 5,578 tools, fills arguments automatically, returns structured answers with stable citation URIs, and claims 'one fast call'. 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 verbose and repetitive. It contains multiple examples, marketing language, and redundancies (e.g., naming query types twice). While front-loaded with a strong directive, it could be cut by half without losing essential information.

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

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

Despite no output schema, the description explains what the tool returns (structured answer with citation URIs) and covers a wide range of use cases with concrete examples. It also provides differentiation from siblings and notes that it works on all tiers, making the tool's behavior fully transparent for an agent.

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

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

Schema description coverage is 100%, with the 'question' property fully described and all alias parameters documented. The description adds minimal value beyond the schema; it merely restates that aliases are accepted and includes examples that are already present in the schema's examples array.

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: answering factual questions by routing to thousands of verified sources and returning structured answers with citations. It uses specific verbs like 'ask' and 'routes', and explicitly distinguishes itself from sibling tools (ask_pipeworx_grounded, deep_research) by naming their different 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?

Provides explicit 'when to use' guidance: 'START HERE for most questions' and lists example query types. It also gives 'when not to use' direction by advising to 'step up' to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for multi-part fan-out queries, which clearly delineates 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 indicate read-only, idempotent, open-world, and non-destructive. The description adds valuable context: it is a beta with candidate routing improvements, currently no candidate is active (retired on a specific date), and results are compared against the stable router. This goes beyond annotations to explain the experimental nature and lifecycle, and does not contradict annotations.

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

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

Three sentences, front-loaded with the core purpose (beta version). Every sentence adds necessary context: the identical nature, the experimental status, usage guidance, and reassurance it's not a stub. 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?

For a tool with one required natural-language parameter and no output schema, the description is highly complete. It covers what the tool does, its relationship to the stable version, experimental status, current state, and how results are used. The response shape is referenced ('same response shape' as ask_pipeworx) and users can infer the rest from the sibling's documentation.

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

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

Schema coverage is 100% with all six parameters being aliases for 'question'. The description says 'same arguments' as ask_pipeworx but does not add new semantic meaning beyond what the schema provides. Baseline of 3 is appropriate since the schema already fully documents parameter semantics.

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

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

The description clearly states it is the beta version of ask_pipeworx, a universal router, and specifies it handles the same 5,578 tools. It distinguishes itself from the stable ask_pipeworx and the grounded sibling by noting the experimental routing improvements, and explicitly says it is currently identical to ask_pipeworx.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared to decide merges. It implicitly tells users to prefer the stable router if they don't want experimental behavior, and reassures that it is a full working router. Missing explicit exclusions like 'not for production use' but that 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?

Description richly discloses behavior beyond annotations: extraction is limited to tool result content, success and refusal return shapes are specified, and refusal reasons are enumerated. It also discloses the extra LLM call cost, which annotations do not cover. No contradiction with readOnlyHint or idempotentHint.

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?

Packed but efficiently structured: front-loaded with the core purpose and distinction, then return contract, refusal semantics, usage guidance, and cost trade-off. Every sentence adds unique, high-value information without redundancy.

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

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

Despite no output schema, the description fully specifies return values and failure modes, which is critical for an agent acting on high-stakes answers. Combined with rich annotations and sibling context, this description is complete for safe 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% and all six parameters are documented as aliases for the same question field. The description adds context about how the question is used ('picks the right tool... fills arguments, fetches the data') but does not materially enhance parameter semantics beyond the schema.

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

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

Description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb/resource and distinguishes itself from sibling ask_pipeworx by emphasizing grounded extraction from tool results. It also lists exact output fields, making the tool's function unmistakable.

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

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

Explicit guidance is provided: use when answers will be 'quoted, cited, or acted on' and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This directly addresses when and when not to use the 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 indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral context: fan-out to multiple data sources, resolver contract with confidence levels, safety mechanisms (low-confidence short-circuit, closed market detection, wide spread warnings), and resolution-rule risk. It also explains parameter effects (depth, include_raw). No contradiction with annotations.

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

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

Description is very long and dense, containing many details. It is structured with line breaks and implied sections, which helps, but it could be more concise without losing critical information. The front-loading of core purpose is good.

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 thoroughly covers response shapes (market analysis, evidence, resolver contract, parent event, news fields), safety mechanisms, and edge cases. It is nearly complete for a complex tool, though a structured overview of the return object would be helpful.

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

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

Input schema coverage is 100%, and description adds significant meaning beyond schema: market can be slug, URL, or question text; depth has quick/thorough with explanation; include_raw summarized vs full. Examples are provided. This enriches the schema with practical use 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?

Description clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and scope (one call). It also provides usage examples and distinguishes itself from sibling tools through its comprehensive nature, though it does not name them explicitly.

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

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

Description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also distinguishes between 'quick' and 'thorough' depth. However, it does not explicitly mention when not to use or compare to alternative sibling tools.

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

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

Description adds detailed data source info (SEC EDGAR, FAERS), off-calendar handling, sorting, and return format, going well beyond annotations that already indicate idempotent read-only behavior.

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

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

Front-loaded with trigger phrases and purpose, every sentence adds value; slightly longer due to rich detail but justified by tool 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?

Fully explains inputs, outputs, data sources, and behavior; no output schema but return format is described; sufficient for 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?

Adds meaning beyond schema by explaining type enum behavior and value formats (tickers for company, names for drug), with min/max items context.

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

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

Description explicitly states tool performs side-by-side comparison of 2-5 companies or drugs in one call, uses trigger phrases, and distinguishes from sequential sibling lookups.

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

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

Strong 'ALWAYS PREFER' guidance over sequential lookups, with clear context for company vs drug types, though no explicit 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 declare readOnly, openWorld, idempotent, and non-destructive hints, but the description adds extensive behavioral context: it never invents data (explicit gaps[]), returns fetchable citation_uri, performs multi-hop iterations, semantically excerpts large records, and states latency expectations. This goes far 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 every sentence delivers critical information. It front-loads account requirements and the main differentiation from ask_pipeworx, then systematically covers functionality, limitations, output format, and timing. No redundancy or filler; structure flows logically.

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 (parallel orchestration, multiple depth levels, rich output packet), the description is remarkably complete. It explains output structure (findings with evidence, confidence, source, timestamps, citations, gaps[], contradictions[]), covers edge cases (unstructured topics return empty gaps), and provides latency expectations. No critical aspect is left undocumented.

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 describes both parameters well. The description adds extra meaning: it explains the depth levels' behaviors (quick=3 facets single hop, standard adds gap recovery + contradictions, thorough adds iterative lead chasing) and notes that thorough requires a paid plan. It also clarifies that question can be broad/multi-part, enhancing schema 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 the tool's purpose: 'Grounded multi-source research across Pipeworx's 1463 STRUCTURED data sources' in one call, with a specific verb (research) and resource (structured data). It distinguishes from siblings by explicitly naming alternatives (ask_pipeworx) and describing unique capabilities like parallel routing to 5,578 tools and findings packets with citations.

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 when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and fallback behavior when not signed in.

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. Description adds that it returns top-N relevant tools with full schemas and examples, and that results are ready to call directly. Some behavior like pagination or error handling is omitted, but overall adequate.

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 starts with a clear one-liner, then provides useful detail including domain list and result format. It is somewhat lengthy but each sentence adds value. Could be trimmed slightly but overall well-structured.

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

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

Given the complexity of a discovery tool with no output schema, the description covers purpose, usage guidance, output structure, and example domains. Missing details like pagination or empty results are minor. Annotations round out the behavioral context.

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

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

Input schema covers all 6 parameters (with aliases) at 100% coverage. Description does not add significant meaning beyond the schema; it only restates that query accepts natural language. Baseline score of 3 is appropriate as schema already delivers the semantics.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and distinguishes itself from sibling tools by positioning as the first call to see available options.

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 you need to browse, search, look up, or discover what tools exist for:' with examples, and advises to call this FIRST before other tools. Could be stronger on when not to use (e.g., direct answer retrieval).

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 read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: fans out across multiple sources, returns specific fields like CIK, filings with URIs, fundamentals sorted by period, patent status (soft-fail after May 2025), news fallback (GDELT→GNews), and LEI via GLEIF. 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 longer but every sentence adds value. It front-loads with example user queries, then details the tool's behavior and outputs. Could be slightly more terse, but structure is logical and efficient.

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

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

Given no output schema, the description thoroughly explains the return values: CIK, company name, recent filings with PIPEworx URIs, fundamentals, patents, news, and LEI. It also notes limitations (patent sunset, name not supported). This is comprehensive 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%. The description adds meaning beyond the schema: clarifies that 'value' can be ticker or zero-padded CIK, and emphatically states that names are not supported, directing to 'resolve_entity' instead. This helps the agent correctly populate the 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 provides specific verb phrases like 'Tell me about X' and lists example queries, clearly stating it returns a full cross-source profile of a US public company. It distinguishes itself from the sibling 'resolve_entity' by noting that names are not supported and that tool should be used first if only a name is available.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also provides a clear when-not-to-use condition: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is valuable beyond the annotations. No contradictions.

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

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

Two sentences, each essential. The first states the purpose, the second provides usage context. 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?

For a simple destructive tool with one parameter and no output schema, the description is complete. It explains what it does, when to use it, and how it relates to 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% with a description for the 'key' parameter. The description adds 'by key' but does not provide additional semantic detail beyond what the schema already states.

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

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

The description clearly states the action 'Delete' and the target 'previously stored memory by key'. It distinguishes itself from sibling tools 'remember' and 'recall' by naming them, implying it is the deletion counterpart.

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 the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. Also provides guidance on pairing with alternatives: 'Pair with remember and recall'.

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. Description adds process details (fetch, extract, emit) and output format, providing behavioral context beyond annotations.

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

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

Concise paragraph front-loads purpose, then process, output, and use cases. Every sentence is informative with no redundancy.

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

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

Given 2 parameters, no output schema, and no nested objects, the description fully covers input, process, output, and use cases, making it complete.

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

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

Schema covers both parameters with descriptions. Description adds examples (e.g., full URL, specific landing page) and context for max_links (default 25, max 50), enhancing meaning.

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 verb 'Generate' and specific resource 'llms.txt file for any URL'. It explains the process and output format, distinguishing it from sibling tools like ai_visibility_check by focusing on llms.txt generation.

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

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

Explicitly lists three use cases: client indexing, personal drafting, competitor auditing. While no explicit 'when not to use', the guidance 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?

Description adds behavioral context beyond annotations by specifying exactly what schema details are returned (fields, geometry type, count, capabilities). Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower; the description complements them well.

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 that front-loads the action and resource, then concisely lists the returned information. Every part is necessary and informative.

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

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

Given the simple input (1 param, well-documented), rich annotations, and no output schema, the description sufficiently explains what the tool does and returns. It does not cover return format details, but the listed components are adequate.

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

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

Schema coverage is 100% with a clear parameter description and example. The main description merely repeats the URL context without adding new meaning or constraints, meeting the baseline for full coverage.

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 specifies verb 'Get' and resource 'ArcGIS Feature/Map Service layer's schema', listing specific schema components. It does not explicitly contrast with sibling tools like 'query_layer', so it misses the distinction criterion for 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?

No explicit when-to-use or alternatives mentioned. The description clearly states the tool retrieves schema by URL, but provides no guidance on when to prefer this over sibling tools such as 'query_layer'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return field names but no additional behavioral context beyond that. Consistent with annotations.

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

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

Two sentences, front-loaded with purpose and return fields, no redundant information. Highly efficient.

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

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

Complete for a simple read-only tool with one optional parameter. Annotations cover safety, description covers purpose and return fields. 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?

Input schema has 1 optional parameter with description, coverage 100%. Tool description does not mention the parameter, so baseline score applies; no added value but no deficit.

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

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

States 'List the caller's active subscriptions' with specific return fields (id, type, params, etc.). Clearly distinguishes from sibling tools like subscribe/unsubscribe by mentioning use for review or cancellation.

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: 'review what you're monitoring before adding more or to find an id to cancel.' Does not give negative guidance but 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?

All annotation hints are false, so the text carries the full burden. It discloses rate-limiting (5/day/identifier), the no-quota/no-cost property, and the claim_token return-and-check mechanism. It also warns against pasting end-user prompts, adding non-obvious behavioral context.

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

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

The description is longer than average but front-loaded and high-signal; every sentence serves a purpose. A small amount of background ('team reads digests daily') is not strictly necessary, so it is not a perfect 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?

Despite having no output schema, the description covers the important return concept (claim_token), enforces usage boundaries, explains rate limits, and provides enough context for a feedback tool with nested optional params. It is comprehensive for its complexity.

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

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

Schema covers all 4 parameters at 100%, so baseline 3 applies. The description adds extra guidance for the message parameter (describe in terms of Pipeworx tools/packs, don't paste end-user prompt) and reinforces claim_token usage, which justifies one step above baseline.

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

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

The description opens with a concrete action ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates exact feedback types (bug, feature/data_gap, praise). It clearly distinguishes this feedback tool from sibling research/query 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 provides explicit when-to-use triggers (wrong/stale data, missing capability, praise) and an explicit exclusion: only report issues for tools served by this Pipeworx connection. It also gives a disambiguation rule for identifying Pipeworx tools and directs users elsewhere for other servers' tools.

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

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

Annotations already state readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h. This enriches transparency beyond annotations but does not mention behavior like rate limits or failure modes.

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

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

The description is comprehensive but not overly verbose. It front-loads the main output and use cases. Some repetition exists (window choice appears in both description and schema), but overall well-structured.

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

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

The tool has one optional parameter, no output schema, and strong annotations. The description explains what is returned (top tools, packs, call volume) and caching behavior. Lacks detail on output format (e.g., count limits), but sufficient given the tool's simplicity.

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

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

Schema coverage is 100% and the schema description already explains the window parameter (default, use cases for each value). The description does not add further meaning, so 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 returns top tools, packs, and call volume over recent windows. It uses specific verbs ('returns') and resources ('trending data on Pipeworx'), and distinguishes from siblings like discover_tools by focusing on aggregated trending signals rather than general discovery.

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

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

Three explicit use cases are provided (discovering hot data, confirming canonical tools, checking alignment). Window selection guidance is given. No explicit 'when not to use' but the use cases imply context; slight gap prevents 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 readOnly, idempotent, openWorld, non-destructive. The description adds rich behavioral details: the monotonicity violation mechanism, partition-sum check, fill check against live book depth, semantic anchor threshold, partition filter, and response format. No contradictions with annotations, and the additional context significantly enhances the agent's understanding of tool behavior.

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

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

The description is well-structured with a clear opening and detailed breakdown of modes. While comprehensive, it is slightly lengthy; however, every sentence adds information (e.g., fill check, semantic anchor). Could be trimmed slightly without losing clarity, but overall 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 fully explains the response format (opportunities array with gap_pp, suggested_trade, etc., and partition_check in event mode). It covers edge cases (fill check, semantic anchor, placeholder filter) and gives fallback guidance. The tool is complex, but the description is complete enough for an agent to understand behavior and expected output.

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

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

Schema covers 100% of parameters but the description adds value beyond schema: for 'event' it notes that full Polymarket URLs are accepted (not in schema), and for 'topic' it explains that the tool searches related events. This extra context justifies a score above baseline 3.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, specifying three modes (no args, event, topic). It distinguishes itself from sibling polymarket_fill_risk by mentioning custom sizing uses that tool, but does not explicitly contrast with other siblings like polymarket_edges or polymarket_edge_tracker, so it slightly misses full differentiation.

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', 'or topic for a themed cross-event scan'. It recommends event mode for specific markets, gives examples of slugs, and advises using polymarket_fill_risk for custom sizing, offering clear context and alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses caching (1h at KV level), edge calculation details (edge_pp_net, kelly fractions, 24h-move warning), and that Fed bets are excluded from ranking. 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?

Despite length, the description is well-structured with numbered segments, bold key terms, and front-loaded purpose. Each sentence adds unique information without redundancy, earning its place.

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

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

The description comprehensively covers output structure (by_segment, fed_candidates, diagnostics), caching, tradeable-edge filters, and model formulas. It compensates for the lack of output schema with detailed response expectations.

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

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

With 100% schema coverage, the description still adds value by explaining knobs like min_partition_leg_kelly and slippage_pp in detail beyond the schema. Examples ('Set to 5000 to drop thin-book opportunities') enhance understanding.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the action (scan and return), resource (Polymarket markets), and distinguishes from siblings by detailing unique model families and segments like MODEL_DRIVEN and STRUCTURAL_ARBITRAGE.

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 targets 'what should I bet on today' agents and explains tradeable-edge knobs (min_liquidity, max_spread_pp) to filter unrealizable edges. It lacks explicit when-not-to-use statements but provides clear context for usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context beyond annotations: history depth is bounded by a 60-day TTL, decay numbers come from daily closes at default slippage (not intraday), and gaps in data occur when no scan happened. This enriches the agent's understanding of tool behavior.

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

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

The description is verbose and includes example text, response field explanation, and limitations. While front-loaded with the core question, it could be more concise to improve readability for agent scanning.

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 two optional parameters, no output schema, and annotations covering safety, the description thoroughly covers return fields, data availability, and computation details. It answers likely agent questions about what the tool returns and its limitations, making it 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 descriptions for both parameters. The description adds default values and a maximum for days, plus explains the response structure (tracked, expired, snapshot_dates), which compensates for the missing output schema. However, it does not add meaning beyond what the schema already provides for the parameters themselves.

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 ('answers') and resource ('edge persistence and decay telemetry') and distinguishes itself from static snapshots like polymarket_edges by highlighting the time dimension and the different trade implications of fresh versus old 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 implies usage for historical edge tracking but does not explicitly state when to use this tool versus alternatives like polymarket_edges or polymarket_arbitrage. No direct 'when to use' or 'when not to use' guidance is provided.

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

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

Although annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds significant behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), explains behavior for different modes, and warns about thin books and forced directional risk. 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 relatively long (~200 words) but well-structured with capitalization for emphasis (REQUIRES, SINGLE-MARKET, BASKET) and front-loads the main purpose. Every sentence adds value, though it could be slightly more concise for a quick scan.

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

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

Despite no output schema, the description comprehensively explains return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, etc.) and covers edge cases (thin legs, forced directional risk, partial fills). Annotations provide safety information. The description is fully complete for a read-only analysis 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?

With 100% schema description coverage, the description adds substantial meaning beyond the schema: it explains side defaults (including auto), differentiates between market and event parameters, and clarifies size_usd interpretation (max spend on buys, target proceeds on sells, settlement notional for baskets). It uses examples and bold formatting for clarity.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, provides specific return fields, and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it (before arb or edge trades > $500).

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns about consequences of partial fills converting arb into unhedged directional positions. It provides clear context for when to use the tool.

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

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

Annotations already declare the tool as read-oriented, open-world, and idempotent. The description adds significant behavioral context: explains compatibility warnings, temporal alignment, skipped cross-type/subtype counters, and that most pre-mapped topics return warnings. 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 thorough and well-structured, with topic, modes, response structure, and safety fields clearly separated. It is slightly long but every sentence adds value, and the organization aids readability.

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

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

Given the tool's complexity (multi-venue, multiple modes, safety checks), the description covers all necessary aspects: input parameters, response format, temporal alignment, skipped comparisons, and compatibility warnings. No output schema, but the description adequately explains the return structure.

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

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

Schema coverage is 100%, and the description adds substantial meaning beyond the schema by listing allowed topic values, providing examples for explicit tickers, and explaining how the two modes interact (topic overrides vs. explicit overrides).

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 calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs like 'cross-venue spread' and distinguishes itself from siblings as the only multi-venue spread tool.

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

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

The description explains two modes of usage (topic shortcuts and explicit tickers), provides examples, and details safety warnings indicating when spreads are not meaningful. It gives clear context for when to use the tool, though it could explicitly state alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds that it returns attribute rows and geometry, and mentions pagination via limit/offset, but does not detail rate limits or behavior with large datasets. No contradiction.

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

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

The description is two sentences, front-loaded with action and resource. Every sentence adds value: stating the purpose, key parameters, and a usage tip. No redundant or missing 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 mentions returning 'attribute rows (and geometry)', which is sufficient. All parameters are covered, and annotations provide safety info. The tool is well-specified for its task, though return format details are minimal.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds minor context (e.g., 'SQL-like where', comma-separated out_fields) and an example, but does not significantly extend the schema's already clear descriptions.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, a specific verb-resource pair. It distinguishes from siblings like layer_info, which likely retrieves metadata, by focusing on data retrieval with SQL-like parameters.

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 examples and suggests sampling with 'where="1=1"' and 'out_fields="*"'. It ties the URL to search_datasets, giving context. However, it does not explicitly state when not to use it or compare to sibling tools like layer_info.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds scoping detail ('Scoped to your identifier') which is valuable context beyond annotations. No contradictions.

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

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

Two sentences, front-loaded with purpose, then usage and scoping. No filler, 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?

For a simple read-only tool with one optional parameter and no output schema, description covers purpose, usage guidelines, and behavioral scoping completely.

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 description per parameter. Description adds context about omitting key to list all, but this is already implied by schema. Baseline 3 is appropriate.

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

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

Description explicitly states the verb (retrieve/list), resource (saved values), and distinguishes from siblings (remember, forget). 'Retrieve a value previously saved via remember, or list all saved keys' is specific and unambiguous.

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

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

Provides concrete examples of when to use (look up user's target ticker, address, research notes) and pairs with remember/forget. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the mark_read flag persists state (flags events as read) and that the feed is also accessible via REST endpoint. No contradictions with annotations; the description clarifies the tool's behavior beyond the structured hints.

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

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

Four sentences, each adding distinct value: verb+resource, returned fields, parameters, and alternative access. Front-loaded with the core action. No wasted words. Efficient and clear.

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 all essential aspects: what the tool returns (source, citation_uri, payload), parameters with examples, side effects (mark_read), and an alternative access method. No output schema is needed given this completeness. The description is self-sufficient for correct 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?

Schema coverage is 100% with descriptions for all 5 parameters. The description adds meaning by providing usage examples (e.g., filter by 'sec_8k') and explaining the behavior of mark_read and since. It also notes the return structure. This enhances the schema's descriptions effectively.

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

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

The description uses a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly states the tool's function and mentions the returned data fields. While it does not explicitly distinguish from sibling tools, the context is sufficient for understanding its scope.

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

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

Provides guidance on filtering options (type, since) and the mark_read behavior. Mentions that 'Polls work fine' and gives an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. Lacks explicit when-not-to-use or comparisons with other tools, but the context is helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds detailed behavioral context: fans out to multiple sources, fallback logic, USPTO soft-fail, return format with citation URIs. No contradiction.

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

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

Dense but well-organized with examples first, then detailed explanation. Slightly long but every sentence adds value. Could be trimmed slightly but remains efficient.

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

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

Despite no output schema, description explains return structure. Covers API sunset, fallback, and window handling. Complete for a complex tool with 3 parameters and multiple data 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 coverage is 100% but description adds meaning: explains 'since' accepts ISO or relative with examples, 'type' is only company, 'value' can be ticker or CIK. Provides usage recommendations beyond schema.

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

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

Description clearly states it is a change feed for a company aggregating SEC, news, and patents. Uses explicit examples like 'What's new with X' and 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?

Explicitly tells when to use this tool vs entity_profile. Explains fallback strategy (GDELT→GNews) and provides parameter usage guidance (e.g., 'Use "30d" or "1m" for typical monitoring').

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 value beyond annotations: it discloses that data is stored as key-value pairs scoped by the agent identifier, and explains persistence behavior (authenticated users get persistent memory; anonymous sessions retain for 24 hours). No contradiction with annotations. A small gap: does not mention any size limits or rate limits.

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

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

The description is efficient: 5 sentences, each contributing distinct information. It front-loads the purpose and then covers usage, persistence, and pairing. 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?

For a simple tool with 2 required string parameters and no output schema, the description is complete. It explains what the tool does, when to use it, how it behaves, and how it interacts 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 coverage is 100% with good descriptions for both key and value. The description provides examples of keys (e.g., subject_property) and values (e.g., findings, addresses), reinforcing the schema but not adding significant new semantic meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides specific use cases (resolved ticker, target address, etc.) and distinguishes from sibling tools like 'recall' and 'forget' by mentioning pairing with them.

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

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

The description explicitly tells when to use this tool ('when you discover something worth carrying forward') and provides concrete examples. It also advises pairing with 'recall' and 'forget'. However, it does not explicitly state when not to use it or mention alternatives beyond those siblings.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context: cascading through multiple internal endpoints, graceful degradation (LEI/FIGI enrichment degrades gracefully, EDGAR identifiers still return), labelling identifiers with their source, and explicitly stating unresolved identifiers. This goes 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 front-loaded with examples and a clear usage directive. The supported types section is somewhat dense but well-organized. Every sentence adds value, though some details (like the parent/ultimate-parent ownership chain) could be more succinct without losing necessary context.

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 what identifiers are returned, how resolution works, and fallback behavior. It covers edge cases like ISIN resolution for non-US issuers, graceful degradation, and replaces manual lookups. This is a complete contextual description for a 2-param tool with rich behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds examples and details about accepted formats (e.g., ticker, CIK, ISIN, or name for 'value'), and explains what 'type' returns. This adds moderate value beyond the schema, but baseline 3 is appropriate since the schema already does the heavy lifting.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific query examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes itself from sibling tools by stating 'Use FIRST whenever you have a name but need an ID', which sets a specific verb+resource+scope.

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

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

The description explicitly says when to use: 'Use FIRST whenever you have a name but need an ID.' It implies the primary context for this tool as a first step before other operations. However, it does not explicitly state when not to use it or list alternative tools like entity_profile for queries where an ID is already known, though the guidance is clear enough.

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

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

The description discloses that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. This adds behavioral context beyond the annotations (readOnlyHint, etc.), which already indicate a non-destructive operation. No contradictions.

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

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

The description is concise (three sentences) and front-loaded with the core action. It efficiently conveys the tool's function, use case, and output without waste.

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

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

Given the tool's moderate complexity (comparison, sub-tool usage, return format) and no output schema, the description adequately covers the return format (ranked list with score, confidence, signal density) and provides a concrete example. It is complete for an agent to understand the tool's value and output.

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 does not add significant new meaning beyond the schema; it reiterates the purpose of the 'entities' parameter but does not enhance understanding of other parameters.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using the verb 'compare' and resource 'AI visibility'. It differentiates from sibling tools like ai_visibility_check (single entity check) and compare_entities (generic comparison) by specifying the AI presence focus.

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 clear use case ('competitive AI-marketing audits') and explains how it works (probes each entity with ai_visibility_check, ranks). However, it does not explicitly state when not to use this tool or mention alternatives, leaving some room for inference.

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=false. The description adds behavioral details such as partial failure handling and the 5-30s delay for bundlephobia's first measurement, which is valuable context beyond the annotations.

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

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

The description is front-loaded with the primary purpose and is dense but not overly long. Every sentence adds value, though minor redundancy could be trimmed (e.g., 'Partial failures degrade gracefully' could be slightly shorter).

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

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

Despite having no output schema, the description thoroughly explains the return content (summary block, per-advisory detail, links, recent alternatives) and failure behavior. It provides complete context for an agent to understand what the tool returns and how it handles edge cases.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: 'Scoped packages (e.g. "@types/node") are accepted' for the package parameter, and version defaults to latest. This provides useful clarification 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's a composite check for npm packages using deps.dev and bundlephobia. It explicitly distinguishes from siblings by noting 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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 usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies when not to use it (non-NPM ecosystems) and directs to alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds value by specifying the exact output fields and the downstream usage hint. 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 two sentences with no wasted words. It front-loads the purpose and immediately provides actionable output details 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?

Given the tool's simplicity (3 optional params, no output schema, safe annotations), the description fully covers what the tool does, what it returns, and how to use the result. No gaps.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds examples and contextualizes the default city, but does not provide substantial extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches City of South Bend GIS open geospatial datasets by keyword and specifies the returned fields (name, summary, record_count, owner/org, feature service url). It also distinguishes from siblings like query_layer and layer_info by mentioning the URL can be passed to them.

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

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

The description tells when to use the tool (keyword search of GIS datasets) and gives guidance on how to use the result by passing the url to other tools. It lacks explicit when-not-to-use or alternatives, but the context is clear enough given the diverse sibling set.

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 provides valuable behavioral details beyond annotations: it mentions the embedding model (BGE-base-en), similarity measure (cosine), windowing (500-char overlapping windows), character limit (200K chars) with truncation and flagging, and that returned passages include character offsets for verification. This complements the annotations (readOnly, idempotent, etc.) without contradiction.

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

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

The description is concise but comprehensive: it covers purpose, usage guidelines, technical details, and pairing in three sentences. Every sentence adds necessary information without redundancy or extraneous text.

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

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

Despite having no output schema, the description explains return values (top-N passages with character offsets and similarity scores) and behavior for long inputs (truncation and flagging). It also mentions the pairing with a sibling tool. The description is complete for a semantic search tool with the given annotations.

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

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

Schema description coverage is 100% for the three parameters. The description adds context such as example queries ('supply-chain risk', 'fiscal year 2024 revenue'), clarifies the truncation behavior for 'text', and explains default for 'limit'. This is more than the schema alone provides, earning a score above baseline.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying the resource ('INSIDE a fetched record') and the verb ('search'). It distinguishes itself from siblings by mentioning its pairing with 'ask_pipeworx_grounded' and explaining when it's useful (when records are too large for prompts).

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

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

The description explicitly tells when to use the tool: 'Use when the record is too big to cram into the prompt'. It also explains how it pairs with ask_pipeworx_grounded for grounding over passages. However, it does not specify when not to use it or explicitly exclude 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 indicate readOnlyHint=false, idempotentHint=true, etc. The description adds valuable context such as the need for an OAuth account, auto-disable of webhooks after 10 failures, and the return of a subscription id. 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 with useful information and front-loaded with the main purpose. However, the delivery section is somewhat verbose and could be more streamlined.

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

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

Given the complexity (3 params, nested objects, five types) and lack of output schema, the description covers types, delivery, constraints, and return value reasonably well. It does not specify the full response structure beyond the subscription id, but this is acceptable.

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

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

Schema coverage is 100%, and the description greatly enriches parameter meaning by providing detailed examples for each type and explaining the delivery object with validation rules and constraints.

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

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

Clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. Distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying its unique function.

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

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

Provides clear prerequisites (Pipeworx OAuth account), lists supported types with example parameters, explains delivery channels, and mentions constraints (phone verification, 10/day cap). However, it does not explicitly state when to use this tool over alternatives like recent_alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. Description adds behavioral context: returns category-bucketed questions from a live catalog, how to call with/without topic. Does not contradict annotations.

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

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

Description is a single paragraph, front-loaded with example queries. Every sentence adds value, but could be slightly restructured for readability; still concise enough.

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

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

Given complexity and no output schema, description explains return format (category-bucketed examples with tool shapes) and usage context (first contact with Pipeworx). Covers needed guidance for an onboarding tool.

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

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

Schema coverage is 100% with one parameter described. Description adds meaning beyond schema by listing possible topic values and explaining effect of omitting topic, plus mentioning return categories.

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 is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings by specifying 'use this FIRST' and naming meta-tools like ask_pipeworx, entity_profile, etc.

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

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

Explicitly says when to use: 'when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also hints at alternatives by naming the meta-tools.

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

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

Description explains that the row is deactivated, not deleted, and historical events remain available via recent_alerts. Annotations already indicate non-destructive (destructiveHint=false) and idempotent, but description adds behavioral nuance without contradiction.

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

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

Two concise sentences front-loading the action. Every sentence adds value without redundancy.

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

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

For a simple one-parameter tool without output schema, the description covers ownership, behavioral effect (deactivation), and relation to sibling tool (recent_alerts). Complete and sufficient.

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

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

Schema coverage is 100% with one parameter 'id', and description adds no additional meaning beyond the schema's already clear description ('Subscription id (uuid) returned by subscribe'). Baseline score of 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id' with a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'recent_alerts' by noting that historical events are preserved via recent_alerts.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), indicating when to use and implicit constraint. Does not explicitly list when not to use, but clarity is high.

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/idempotent annotations, the description reveals the underlying routing logic: SEC EDGAR + XBRL fast path for company-financial claims with exact percent-delta math, and a grounded pipeline for all others. It also clearly defines the ambiguous verdicts could_not_verify and unsupported, warning that could_not_verify must not be treated as evidence.

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

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

The description is longer than average, but it is well-structured: trigger phrases, then purpose, routing details, return values, and a critical caveat. It is front-loaded with the main purpose and every section carries useful information, though it could be slightly tightened.

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 thoroughly explains the return structure (verdict, actual value, pipeworx:// citation, reasoning) and the meaning of each verdict, especially the nuanced could_not_verify and unsupported cases. It also notes the tool replaces 4–6 sequential calls, giving the agent a complete picture of scope and behavior.

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

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

The input schema already fully documents both parameters: claim has natural-language examples, and tolerance_pct has a description covering range, default, and intent. The description adds only tangential context about 'exact percent-delta math' but does not materially extend the schema's semantics. With 100% schema coverage, 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 opens with concrete trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and then states the core purpose: 'natural-language claim verification against authoritative sources.' It uses specific verbs and clearly distinguishes itself from sibling tools by packaging multiple sequential steps into a single verification call.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct,' and goes on to explain how claims are routed (company-financial vs. any other). This gives clear when-to-use context, but it does not name alternative tools or explicitly state when not to use it, so it stops 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.