Arcgis Fauquier

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the default model is Workers AI Llama-3.3-70b (free), passing `_apiKey` probes Anthropic with direct billing, and the return shape includes per-model {score, confidence, signals, raw_response}.

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 three sentences long, front-loaded with the primary action, then provides key behavioral details (default/free model, optional API key), and ends with use cases. Every sentence contributes unique information with no repetition or filler.

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

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

The description covers the core behavior, output structure, optional API key auth, and typical use cases. With no output schema, it explains the return format well. It omits potential edge cases like error handling when `_apiKey` is missing, but overall it is complete for a read-only probing tool.

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

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

The input schema already includes descriptions for all 4 parameters, so schema coverage is 100% (baseline 3). The description adds contextual meaning by explaining the default model and when `_apiKey` is needed, but these details are also inferable from the schema. No significant additional 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?

The description clearly states the action ('Probe one or more LLMs') and the resource ('a business / brand / product / topic'), while specifying the output ('score visibility (0-100) per model'). It distinguishes itself from sibling tools like ask_pipeworx by focusing on scored visibility rather than general Q&A.

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

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

The description provides explicit use-case context ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring'). It does not list exclusions or name alternative tools, but the context is clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond these: it explains that the tool returns citations (stable pipeworx:// URIs), auto-fills arguments, and works on every tier. It does not mention potential latency, failure modes, or limits, but for a read-only query router this is acceptable. The description goes beyond mere annotation repetition and enhances understanding.

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 densely packed with critical routing information, examples, and alternatives. It front-loads the 'PREFER OVER WEB SEARCH' directive and the main use case. Some redundancy exists (repeated mention of news), and it could be trimmed slightly, but overall every section earns its place for a tool that serves as a default entry point across many domains.

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 that routes to thousands of sources, the description is remarkably complete: it covers scope (data types, domains), output format (structured answers with citations), default behavior, and when to step up to alternatives. No output schema exists, but the description's explanation of citation URIs and the 'START HERE' guidance covers all an agent needs to invoke it correctly.

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

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

The schema fully documents the single semantic parameter 'question' with all aliases (q, text, input, query, prompt) and explains it accepts natural language. Schema coverage is 100%, so the baseline is 3. The description provides numerous example questions, which illustrate value formats but add no new semantic meaning beyond what the schema already states. It is sufficient but not additive.

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: routing questions to one of 5,581 tools across 1,463 verified sources and returning structured answers with citation URIs. It explicitly differentiates from web search and names successor tools like ask_pipeworx_grounded and deep_research, making its role 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?

The description provides extensive usage guidance, including trigger phrases ('what is', 'look up', 'find'), concrete examples, and explicit conditions for escalating to ask_pipeworx_grounded (hallucination-resistant single answer) or deep_research (broad multi-part questions). It also notes coverage for breaking news, leaving no ambiguity about when to use this tool versus siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond the annotations: it is a fully working router (no fallback), the experimental edge, and routing improvements may be active or retired, which helps the agent understand its operational 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 three sentences with zero fluff. The first sentence defines what it is, the second gives current status, and the third instructs usage and reinforces it is a full router. Information is front-loaded and every sentence earns its place.

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

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

Given the tool's complexity (a universal router with thousands of tools) and lack of output schema, the description is quite complete: it states it is identical to ask_pipeworx in response shape, tells the agent it is fully operational, and describes the current experimental state. It doesn't enumerate response fields, but the reference to the stable version's response shape covers the essential information an agent needs.

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 has 100% coverage, documenting question and five aliases with identical semantics. The description adds nothing about parameters, but none is needed since the schema is explicit and self-explanatory. Baseline of 3 applies.

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

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

Clearly identifies the tool as the beta version of ask_pipeworx, a universal router with 5,581 tools and the same arguments and response shape. It differentiates from siblings by positioning itself as the experimental edge with candidate routing improvements, making its purpose and relationship to ask_pipeworx explicit.

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

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

Provides explicit usage instruction: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also notes current state (no active candidate) so the agent knows it matches stable behavior, effectively conveying when to select this tool over 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 cover read-only/open-world/idempotent, but the description adds crucial behavior: explicit refusal with specific refusal_reason values, evidence as verbatim quote, and the extra LLM call cost. This goes well beyond the annotation hints and prepares the agent for 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?

Dense but well-organized: starts with the core value prop, explains mechanism, then return contract, then usage guidance. Every sentence adds distinct information, and the critical usage/cost trade-off is placed at the end as a decisive factor.

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?

A complex tool with routing, refusal modes, and a structured return contract. The description covers the return fields, refusal reasons, usage criteria, and cost trade-off. No output schema exists, but the description fully substitutes by specifying the return structure. Nothing essential is missing.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description clearly states a specific function: a hallucination-resistant answer mode that routes to tools and extracts answers only from fetched data. It explicitly contrasts with ask_pipeworx, so an agent can distinguish it from siblings without opening schemas.

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

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

Provides explicit when-to-use ('whenever an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups' due to extra LLM call). Names the alternative tool directly, leaving no ambiguity.

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

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

The description richly details behavior beyond the annotations (readOnlyHint, idempotentHint, etc.): fan-out parallelism, resolver confidence levels, parent_event extraction, news fallback with _fallback_attempted, low-confidence short-circuit, market_closed_or_inactive blocking, spread warnings, and cancellation-rule risk. This far exceeds the baseline and is fully consistent with annotations.

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

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

The description is long but front-loaded with the core purpose, and every subsequent section adds specific value (classifiers, fan-out examples, response contract, safety). It is dense and information-rich, but slightly verbose for quick scanning. The structure is logical and each subsection is clearly separated.

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

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

Given there is no output schema, the description fully documents return values: market, analysis, evidence, market_match_confidence, parent_event, news fields, and statuses. It also covers edge cases like low-confidence matches, closed markets, wide spreads, and resolution-rule risk. This is exceptionally complete for a complex tool.

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

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

The input schema already provides 100% coverage for all three parameters (market, depth, include_raw), including descriptions and examples. The description does not add much beyond the schema, though it reinforces accepted input formats (slug, URL, question text). Baseline 3 is appropriate because the schema 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_edges or validate_claim by focusing on single-market research with fan-out to data sources. The scope is explicit: resolve market, classify bet, fan out, return evidence packet.

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

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

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It gives clear context for when to use, but does not name alternative tools or exclusions. The blocking behavior and safety short-circuits further guide invocation, but explicit sibling differentiation is missing.

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 read-only, open world, idempotent, non-destructive. The description adds significant behavioral detail: data sources (SEC EDGAR/XBRL, FAERS), specific fields pulled, handling of off-calendar fiscal years, result sorting by primary metric, and return of citation URIs. 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 long but every sentence delivers critical information. It front-loads the core purpose with trigger phrases and then systematically details type-specific behavior, data handling, and output features. It could be trimmed slightly, but it's well-organized.

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

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

With two parameters, no output schema, and strong annotations, the description covers all necessary aspects: input format, type-specific behavior, data sources, sorting, and citations. It even mentions handling of off-calendar fiscal years, ensuring no user ambiguity.

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

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

The schema's 100% coverage already defines type and values well, but the description enriches semantics by explaining what metrics each type pulls ('10-K revenue + net income + cash + long-term debt' for companies; 'FAERS adverse-event counts, FDA approval counts, active trial counts' for drugs) and giving formatting examples for values.

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 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call,' with specific trigger phrases and clarifies the scope. It distinguishes from single-entity lookups by noting it 'Replaces 8–15 sequential lookups,' making its purpose unambiguous.

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

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

It explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' provides examples of queries that should trigger it, and explains the difference between type='company' and type='drug,' thus giving clear when/why guidance.

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

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

Documented behaviors go far beyond annotations: parallel routing across 5,581 tools, verbatim evidence + fetched_at + stable pipeworx:// citation per finding, explicit gaps[] never-invented behavior, hop-based depth semantics, and a note that prospects without matching coverage yield empty gaps. No annotation is present, so the description carries full burden and succeeds.

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?

Long but front-loaded with the critical account/pricing requirement first)Skip the examples. Just give the JSON response.

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 enormous complexity (1463 sources, 5,468 tools, 3 depth levels, paced behavior), the description covers prerequisites, latency, output structure, limitations)Skip. The sentence ordering makes it digestible.

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 lists question + depth with minimal per-param text. The description adds substantial semantics for the depth values (quick=3 facets, standard adds gap-recovery + contradictions, thorough adds lead-chasing and costs more), and clarifies what the question should be (broad/multi-part vs single lookup). Far 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?

States a precise verb+resource: conducts structured multi-source research across 1,463 specific data source types in one parallelized callsingles out that it is NOT open-web search, and explains what it returns (findings with evidence, sources, citations, gaps[]). Explicitly distinguishes from ask_pipeworx and deep_research siblings by query shape.

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?

Gives explicit when-to-use (broad/multi-part, compare X vs Y over structured sources) and when-not-to (breaking current news, single lookups) with named alternatives and the conditions that select them. Also discloses the auth/sign-in constraint and the paid depth tier.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it returns ready-to-call tools with full schemas, eliminating the need for a second schema lookup. No contradiction with annotations is present.

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

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

The description is front-loaded with the core purpose and usage guidance. The enumerated list of domains is somewhat long but serves to communicate the tool's broad coverage. Each sentence adds information, though a few domain examples could be trimmed without loss.

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

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

There is no output schema, but the description explicitly describes the return content (names, descriptions, full input schemas). Combined with the annotations, this is sufficient for an agent to understand what to expect. The tool's scope and first-use recommendation are well covered.

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 has 100% parameter description coverage and thoroughly explains the query parameter and its aliases. The description's mention of 'describing the data or task' maps to the query parameter but doesn't add new semantic detail beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Find tools by describing the data or task.' It then enumerates a broad set of domains (SEC filings, financials, FDA drugs, etc.) and clarifies that it returns top-N tools with schema info, clearly distinguishing it from sibling tools like search_datasets or search_within.

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 the agent to 'Use when you need to browse, search, look up, or discover what tools exist' and to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides both positive and negative usage context, even without naming specific alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields; uses GDELT→GNews fallback; mentions patents API sunset soft-fail. No contradiction with annotations.

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

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

The description is a dense paragraph but every sentence provides value: examples, usage guidance, return fields, limitations, and fallbacks. It is slightly long but front-loaded with query examples. No wasted words, though a structured list could improve scannability.

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

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

Given the tool's complexity and the absence of an output schema, the description is thorough. It details the return fields (CIK, filings with URIs, fundamentals, patents, news, LEI), explains the data sources, and covers limitations (names not supported, patents sunset). The description is fully complete for the agent to decide 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 both parameters are fully described with examples. The description repeats these examples but does not add new semantic meaning beyond what the schema already provides. Since the schema carries the burden, a 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 what the tool does: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs and resources, and provides multiple example queries. It distinguishes from siblings by explicitly preferring this tool over chaining single-pack SEC/XBRL/news lookups and by referencing use of resolve_entity for name-only inputs.

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

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

Usage guidance is explicit: use this tool when the user asks for a holistic view, and prefer it over chaining single-pack lookups. It also gives an exclusion (names not supported, use resolve_entity first) and notes behavioral details like the patents API soft-fail. This is a textbook example of when-to-use guidance.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true. The description adds no new behavioral context beyond the usage examples; it simply restates the deletion concept. No contradiction, but no added value beyond annotations.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence contributes (purpose + usage guidance). No wasted 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?

For a simple one-parameter delete tool with strong annotations, the description is fairly complete. It covers purpose, usage, and sibling pairing. It doesn't mention error cases or return values, but these are less critical for a destructive action with idempotent semantics.

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 single 'key' parameter with 'Memory key to delete'. The description does not add meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Delete a previously stored memory by key') with a specific verb and resource, distinguishing it from sibling tools like remember and recall.

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

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

It provides explicit guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier. Pair with remember and recall.' This clearly indicates when to use and names alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds the operational pipeline (fetches, extracts, emits) and output format, which provides useful behavioral context without contradicting annotations.

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

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

Three sentences, each contributing uniquely: purpose, process, and use cases. No redundant wording, making it efficient and 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?

Output format is explicitly described as a single text blob in llms.txt markdown, which compensates for the lack of an output schema. Combined with use cases and annotations, the description provides sufficient context for a moderate-complexity 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 both url and max_links described in the schema. The description reinforces the URL parameter as 'any URL' but adds little beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool's function: generating a llms.txt file for any URL, with specific actions (fetch, extract, emit). It distinguishes from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than presence checking.

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

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

The description provides three concrete use cases (client site indexing, personal project drafting, competitor auditing), giving clear context on when to use it. However, it does not mention explicit exclusions or alternative tools, so it earns a 4 rather than 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by specifying exactly what information is returned (fields, geometry type, record count, capabilities), which goes beyond the annotations and helps the agent anticipate the tool's output.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource, then lists specifics. Every phrase earns its place, with zero filler or repetition of annotations.

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

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

For a tool with one parameter, strong annotations, and no output schema, the description is complete. It defines the input (URL), the purpose (schema retrieval), and the expected return items (fields, geometry type, count, capabilities). No critical information is missing.

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

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

Schema description coverage is 100%, and the single parameter 'url' is clearly documented as a Feature/Map Service layer URL. The tool description's mention of 'by url' adds no significant meaning beyond the schema. Baseline 3 applies because the schema already carries the semantic weight.

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

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

The description opens with a specific verb 'Get' and names the resource 'an ArcGIS Feature/Map Service layer's schema'. It enumerates the exact return items (fields, geometry type, record count, capabilities), making its purpose unambiguous and distinct from sibling tools like query_layer that likely retrieve features.

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 clearly implies the use case: when you need schema information for an ArcGIS layer. It does not explicitly name alternatives or exclusions, but the phrase 'schema by url' sets a clear context. A brief note about using query_layer for data queries would strengthen this, but it is not required.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by specifying the return fields (id, type, etc.) and scope (caller's active subscriptions). It doesn't contradict annotations, though it doesn't mention pagination or rate limits.

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

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

Two sentences: first gives action and output, second gives usage guidance. No redundant information, perfectly sized.

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

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

For a simple list tool with one optional parameter, the description covers purpose, return fields, and usage context. No output schema exists, but return fields are listed directly, making it self-contained.

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

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

The schema fully documents include_inactive with its description and default, so the description adds no extra parameter semantics. Baseline 3 applies due to 100% schema 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?

The description clearly states the tool lists the caller's active subscriptions, which is a specific verb and resource. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing, and it enumerates return fields.

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 to use this to review current monitoring before adding more and to find an id to cancel, providing clear when-to-use guidance. This implies subscribe/unsubscribe as 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 are all false, providing little signal, so the description bears full responsibility. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed and what changed'). These are behavioral traits a caller must know.

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 front-loaded with purpose and usage, and each subsequent sentence adds a distinct operational fact (exclusions, token behavior, rate limit, quota impact). It reads as a compact spec rather than padding. The structure proceeds logically from what → when → when not → how → consequences.

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 four parameters, one nested object, and no output schema, so the description must explain the call contract. It does: a submission returns a claim_token when filed anonymously, and that token can be used later to retrieve status. It also states team response cadence ('digests daily') and the connection-scope limitation. This is sufficient for an agent to know exactly what to expect and how to handle the result.

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 4 parameters with their own descriptions, giving a baseline of 3. The tool description adds meaning by mapping type values to real-world triggers ('bug' = wrong/stale data, 'feature/data_gap' = missing catalog entry), and explains claim_token's dual use as a follow-up handle ('pass the pwfb_… token that filing returned, with no other arguments'). It also advises on message content ('don't paste the end-user's prompt'), which complements 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly specifying the action (send feedback) and target (Pipeworx team). It then enumerates use cases (bug, feature/data_gap, praise), distinguishing it from sibling tools like ask_pipeworx or discover_tools by centering on reporting rather than querying. The scope limitation to 'tools served by this Pipeworx connection' further disambiguates from other MCP servers.

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

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

It explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also tells when not to use: 'if the tool came from a different MCP server... file it with that server instead.' This exclusion is crucial and also mentions alternatives (file with other server). Additional formatting guidance (don't paste end-user prompt) and the token-based follow-up complete the usage picture.

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

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

Beyond the read-only/idempotent annotations, the description discloses that data is self-aggregated from CF analytics-engine, contains no PII, and is cached 5min-1h. These details add meaningful context about data provenance and call behavior that annotations do not convey.

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

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

The description is moderately sized but efficiently structured, with a clear definition, use-case bullet points, and data provenance note. It is front-loaded with the core purpose and every sentence contributes value, though it could be trimmed slightly.

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 only one optional parameter and rich annotation coverage, the description covers what is returned, the window options, use cases, data source, and caching behavior. This makes it sufficient for an agent to invoke the tool confidently despite lacking an output schema.

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

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

Schema already documents the single window parameter with an enum and explanation of short vs. long window trade-offs. The description's mention of the window options adds no new semantics beyond the 100% schema coverage, so baseline 3 is appropriate.

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

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

Description opens with a specific statement of what the tool returns ('top tools, top packs, and total call volume over a recent window'), clarifying the aggregation nature and distinguishing it from sibling search/discovery tools. The verb 'Returns' and resource ('top tools, top packs, total call volume') are precise.

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 'Useful for:' list provides three explicit scenarios, giving clear context for when to use this tool (e.g., discovering hot data sources, confirming canonical tool choice). However, it does not explicitly name alternatives or when-not-to-use conditions, so it lacks explicit exclusions.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context beyond that: partition filter rules (dropping placeholder slugs, >20% returns null), semantic anchor with 0.30 Jaccard threshold, and a critical fill check warning (realizable_edge_pp <= 0 means do not trade). These details tell the agent exactly what side effects or caveats to expect. No contradiction with annotations.

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

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

The description is long but well-structured with capitalized section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. Almost every sentence carries information, but it is dense enough that it might be slightly overwhelming; however, it avoids redundancy and front-loads the core purpose. Given the complexity, this structure earns a high but not perfect score.

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

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

The tool is complex with three modes, filters, and a fill-check subprocess, and there is no output schema. The description covers all of this: response structures for opportunities[] and partition_check, fill_check fields, filters, and coordination with a sibling tool. It even explains a failure condition (realizable_edge_pp <= 0). No major behavioral or return-value gaps remain.

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 has 100% description coverage for both parameters, so the baseline is 3. The description enriches this by explaining mode-specific behaviors (e.g., event walks child markets and checks ordering; topic searches related events and flattens markets), plus the no-arg default (trending_scan). It provides example slugs and clarifies acceptance of full URLs, going beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly delineates three modes (trending scan, event, topic), making the tool's purpose and scope unambiguous. It also distinguishes from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection logic.

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 recommends when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It also contrasts cross-event vs single-event capabilities ('Cross-event mode catches ... patterns that single-event misses') and directs users to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.' This is explicit when-to-use guidance with named 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, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds significant behavioral detail beyond these: model family specifics, Kelly caps, 24h-move warning, tradeable-edge knobs, diagnostics funnel counters, and KV-level caching keyed on knobs. 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 very long and dense, but it is structured with uppercase section markers and front-loaded with a clear purpose. Every sentence contributes technical detail, but the sheer volume makes it less concise than ideal. It earns a 3 because it packs valuable info but sacrifices brevity.

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

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

Despite lacking an output schema, the description thoroughly documents the response structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and all filter knobs. This is complete for a complex analytical tool with no output schema.

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

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

The input schema already covers all 9 parameters with detailed descriptions (100% coverage), so baseline is 3. The description adds extra meaning by explaining the distinction between min_kelly and min_partition_leg_kelly (basket trades don't compose to single-leg Kelly) and how min_liquidity/max_spread_pp gate realizable edges, which is valuable beyond the schema's field-level docs.

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 scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly targeting 'what should I bet on today.' This distinguishes it from siblings like polymarket_arbitrage by focusing on directional edge discovery rather than pure 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?

Provides strong usage context ('Built for what should I bet on today', avoids paging hundreds of markets) and explains tradeable-edge filters and that Fed bets are excluded from ranking. However, it does not explicitly name alternative sibling tools or provide direct 'use instead of X' guidance.

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

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

Beyond readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral detail: snapshots are written on cache-miss (so gaps mean no scan), history is bounded by a 60-day TTL, decay is computed from daily closes net of slippage (not intraday), and expired opportunities are tracked with lifespan. No contradictions with annotations.

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

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

The description is long but every sentence carries necessary information. It is front-loaded with purpose, then clearly delineates Args, RESPONSE, and LIMITS sections. No fluff; even the parenthetical examples ('the latter is wide for a reason nobody is willing to take') provide useful intuition.

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

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

With no output schema, the description fully documents return fields: tracked[] with full time-series, trend categories, edge_pp_net signed values, expired[] with lifespan, and snapshot_dates[]. It also explains data gaps and TTL constraints, making the tool's behavior comprehensible without needing additional references.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that 'window' selects the snapshot family ('1wk' default, also 24hr/1mo) and that 'days' has a max of 30, which aligns with the schema's clamp range. This contextualizes parameters beyond simple types/defaults.

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 opens with a precise statement: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and differentiates itself from sibling polymarket_edges by focusing on historical tracking rather than current edge values.

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 when to use this tool—when understanding edge persistence or decay matters—and contrasts a fresh edge versus a 3-week-old edge. It does not explicitly name alternative sibling tools (e.g., polymarket_edges) for current snapshots, but the context suggests the distinction clearly enough for tool selection.

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

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

Even with annotations declaring readOnlyHint and idempotentHint, the description adds substantive behavioral detail: it walks the order book ladder, returns fill-quality metrics (vwap_fill_price, slippage_pp, verdict), and highlights partial-fill risks like 'forced_directional_risk.' It also discloses the failure mode of unhedged positions from partial basket fills, which is crucial beyond the basic safe-read annotation.

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

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

The description is long but well-structured with uppercase mode labels and unordered lists of return fields. It is front-loaded with the core purpose, and every sentence carries relevant detail for a complex dual-mode tool. However, it is verbose enough that it could be tightened without losing value, so it does not earn a perfect conciseness score.

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 (two modes, 4 params, no output schema), the description fully compensates: it explains both modes, parameter interpretations, default values, return fields, per-leg detail, and the specific risk of partial basket fills. It also names sibling tools and provides actionable pre-trade guidance, making it complete for an AI agent to decide when and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds mode-dependent semantics that the schema lacks: `size_usd` means 'max spend' in single-market but 'settlement notional' in basket mode, and `side` has different defaults per mode. It also clarifies the REQUIRES one-of constraint (`market` vs `event`), which is not in the schema. That goes beyond the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by framing this as a fill-risk validator rather than a signal generator. The two-mode (single-market/basket) structure further clarifies exactly what the tool does.

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

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

The description explicitly states when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also defines when to use single-market vs basket mode, and requires either `market` or `event` as a precondition, giving clear contextual guidance.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description adds meaningful behavioral context beyond that: it explains how the tool signals whether bet shapes are equivalent, when spreads are arbs vs noise, and what compatibility_warning cases mean. It also discloses skipped_cross_type/subtype counters and temporal alignment as internal safeguards—transparency far beyond the annotation baseline.

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 densely packed with essential information and clearly labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose and then uses structured bold labels. While verbose, every sentence contributes to safe and correct invocation—no fluff, but it could be trimmed slightly without losing value.

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

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

With no output schema, the description carries full responsibility for return values, and it delivers: it explains leg-by-leg prices, the spread format, compatibility warning triggers, temporal alignment, and skipped cross-type counters. For a tool with this complexity and nuanced safety caveats, the description gives an agent everything needed to decide when to invoke it and how to interpret results.

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 per-parameter descriptions, so the baseline is 3. The tool description adds extra semantics by explaining mode behavior (topic shortcuts vs explicit overrides), the precedence rule ('Overrides the topic-mapped Kalshi side'), and the response structure tied to parameters. This enriches parameter understanding beyond the bare schema definitions.

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

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

The description opens with a specific verb+resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly defines the tool's unique scope (cross-venue comparison) and distinguishes it from sibling tools like polymarket_arbitrage, which likely operate within a single venue. The two-mode mechanism and explicit examples further pin down the intended use.

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

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

The description provides explicit usage context: when to use topic shortcuts versus explicit tickers/slugs, and it details when NOT to trust the output via compatibility_warning and temporal_alignment=false. It even cautions that 'pre-mapped ≠ tradeable.' However, it does not name alternative tools, so it falls short of the explicit alternatives criterion for 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 declare read-only, idempotent, and non-destructive behavior. The description adds context beyond annotations by stating the return includes attribute rows and geometry, and provides a sampling tip (where="1=1" + out_fields="*"). 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 four short, focused sentences with no fluff. It front-loads the core purpose, then lists query options, return content, and a usage tip. Every sentence earns its place.

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

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

For a six-parameter tool with no output schema, the description covers the purpose, usage context, return content, and provides a practical tip. The schema handles parameter details, and annotations cover safety. Missing specifics like geometry format are minor given the high-level description.

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 at 100%, so baseline is 3. The description adds value by connecting the URL parameter to search_datasets and offering a practical sampling pattern, plus noting SQL-like syntax for where. This exceeds 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 it queries an ArcGIS Feature Service / Map Service layer by URL, with specific verbs and resource. It also references search_datasets as the source for the URL, distinguishing it from sibling tools like layer_info or search_datasets.

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

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

The description implies usage after obtaining a URL via search_datasets, giving clear context. It does not explicitly name alternatives or exclusions, but the prerequisite is clear and sufficient for typical use cases.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond annotations: the scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the behavior of listing all keys when the key argument is omitted. 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 three sentences long, front-loaded with the primary action, and every sentence adds value—usage context, scoping, and relationship to sibling tools. No redundant or filler content.

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

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

Given the tool's simplicity and the lack of an output schema, the description adequately explains return behavior (a value or list of keys) and the scoping context. It could mention error cases like a missing key, but for this lightweight retrieval tool the description is sufficiently complete.

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

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

With only one parameter and 100% schema description coverage, the schema already documents the 'key' parameter. The description reiterates the omit-to-list-all behavior but adds little new semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly specifies the verb 'Retrieve' and the resource 'a value previously saved via remember', and also covers the alternate behavior of listing keys when the argument is omitted. It distinguishes itself from sibling tools by explicitly mentioning 'remember' and 'forget'.

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

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

The description explains when to use the tool ('to look up context the agent stored earlier') and gives concrete examples ('target ticker, an address, prior research notes'). It also provides pairing guidance with 'remember' and 'forget', though it doesn't explicitly state when not to use it.

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

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

The annotation readOnlyHint=true is contradicted by the description's statement 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which describes a state-changing side effect. Since the description discloses a write behavior while the annotation claims read-only, this is a direct contradiction. The annotation should be updated or the description should clarify that marking read is an optional mutation separate from the read-only core operation.

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 composed of four sentences, each delivering distinct information: purpose, return fields, filtering and mark_read behavior, and an alternative endpoint. It is front-loaded with the main action and avoids redundancy, though it is slightly dense with multiple clauses in the first sentence. Overall, it is efficient and 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 there is no output schema, the description appropriately explains the return shape (source, citation_uri, raw payload). It also covers the key behavioral aspects (mark_read, filtering, polling feasibility) and supplies an external endpoint for alternative access. Minor gaps include not elaborating on unread_only or pagination beyond the schema, but the description is sufficiently complete for a straightforward feed-reading tool.

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

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

The input schema has 100% coverage with descriptive entries for all parameters, providing a solid baseline. The description adds extra value by illustrating the type filter with an example ('sec_8k'), specifying that 'since' is an ISO timestamp, and explaining the functional effect of mark_read in the context of the persisted feed. This goes beyond the schema's bare descriptions.

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

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

The description clearly states the tool's function: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull/receive events), and distinguishes it from siblings like list_subscriptions and recent_changes by focusing on alert events written to a persisted feed. The mention of source, citation_uri, and raw payload adds specificity.

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

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

The description provides usage context, including filtering by type and since, and explains the mark_read option for controlling which alerts are returned on subsequent calls. It also mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, though it does not explicitly compare with sibling tools. This is clear guidance for common use cases.

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?

Even though annotations already indicate read-only, idempotent, and non-destructive behavior, the description adds valuable behavioral details: fan-out to multiple sources (SEC, GDELT→GNews, USPTO), the GDELT preference with GNews fallback on rate limits/5xx, and the USPTO soft-fail due to API sunset. This goes beyond annotations and prepares the agent for edge cases.

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 every sentence provides functional detail (examples, fallback logic, parameter formats, output structure). It's dense rather than wasteful; however, it could be broken into shorter sentences or bullet points for easier parsing, so a 4 is appropriate.

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

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

Given the tool's complexity (multiple data sources, fallbacks, soft-fail, custom `since` formats) and no output schema, the description fully covers expected outputs: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also references the sibling tool for static profiles, making the context 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?

The schema covers all three parameters, but the description enriches meaning significantly: 'since' accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y'), and 'value' can be a ticker or zero-padded CIK. This expands on the schema's basic descriptions and reduces ambiguity.

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

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

The description clearly states the tool's function: 'change feed for a company in the last N days/weeks/months in ONE parallel call' with concrete example queries. It also differentiates from the sibling entity_profile by specifying when to use each, providing strong purpose clarity.

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 given on when to use this tool vs the alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also describes fallback behavior for news sources, giving the agent clear context for expected behavior.

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 note idempotentHint=true and readOnlyHint=false, but the description adds important behavioral context: persistence is session-dependent (anonymous 24h vs authenticated permanent), and memory is 'scoped by your identifier.' This goes beyond the structured fields and helps the agent understand side effects and retention.

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

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

The description is four sentences, all informative, with the core action stated first. It is efficient and well-structured, though slightly longer than strictly necessary; every sentence contributes to usage, persistence, or integration guidance.

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

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

For a simple two-parameter tool with no output schema, this description is fully complete. It covers what the tool does, when to use it, persistence semantics, and how it relates to siblings recall and forget. No critical operational detail is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces the key-value semantics with examples (ticker, address, preference) but does not fundamentally add meaning beyond the schema's own examples and type descriptions. The value field is already described as 'any text,' so the description adds only marginal clarification.

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' with a specific verb ('save') and resource (key-value pairs). It distinguishes from siblings by explicitly referencing companion tools recall and forget, making its role in the tool family unambiguous.

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

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

The description gives concrete usage guidance: 'Use when you discover something worth carrying forward (a resolved ticker, a target address, a user preference, a research subject)' and explains why (to avoid re-lookup). It mentions alternatives (recall, forget) but does not explicitly state when not to use this tool, so it misses the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds important behavioral context beyond these: graceful degradation when GLEIF or OpenFIGI are unavailable, cascading internal lookups, and explicit handling of unresolved identifiers under an 'unresolved' field. This enriches the agent's understanding of reliability and error handling. No contradictions with annotations.

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

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

The description is long but well-structured: it starts with example queries, then a usage guideline, then detailed subsections for each entity type. Every sentence adds value—covering return fields, data sources, and edge cases. While it could be slightly more concise (e.g., reducing the inline detail in the company section), the structure makes it scannable 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?

Despite lacking an output schema, the description comprehensively explains what the tool returns: for company, it lists CIK, ticker, company_name, LEI, FIGI with source labels and an unresolved field; for drug, it lists RxCUI, ingredient, brand, and citation. It also covers edge cases (ISIN resolution, degraded enrichment when sources are down). The description is complete for an entity resolution tool with two modes.

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 substantial context: for 'type', it details the two supported types and what identifiers each returns (including cross-source identity spine for company and RxNorm data for drug). For 'value', it provides examples (ticker, CIK, ISIN, brand/generic names) and explains special behavior like ISIN-to-LEI mapping. This far exceeds what the schema alone offers.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries and explicitly says 'Use FIRST whenever you have a name but need an ID.' This distinguishes it from sibling tools like entity_profile (which works with existing IDs) and compare_entities.

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

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

The description includes the directive 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to invoke this tool. It details supported entity types and inputs, and notes that it replaces manual lookups. However, it does not explicitly state when NOT to use it or mention alternatives, though the sibling list makes the context fairly clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it probes via ai_visibility_check, ranks by score, and returns score, confidence, and signal density. It does not discuss rate limits or authentication intricacies, but the schema covers the _apiKey parameter. This exceeds the minimum required given annotation coverage.

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

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

The description is four sentences with no fluff. It front-loads the primary action, then delivers key details (sub-probe method, output fields, use case). Every sentence adds value, and the format is scannable.

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

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

There is no output schema, so the description must explain returns; it does ('ranked list with score, confidence, signal density'). It also conveys the entity-count constraint (2-8, from schema) and the comparative context. Combined with the complete schema and annotations, this is fully sufficient for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 100%: every parameter is described in the schema. The description does not add new parameter-specific information beyond what the schema already provides, except for reiterating that the first entity is treated as the subject, which is already in the schema. Thus the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'), and distinguishes from the sibling tool 'ai_visibility_check' by emphasizing multi-entity comparison. It also details the behavior (probes, ranks, surfaces most/least recognized) and the output (ranked list with score, confidence, signal density), making the tool's purpose unmistakable.

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

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

The description explicitly mentions a use case ('competitive AI-marketing audits') and provides a concrete example, which tells the agent when to use it. It implies using the sibling tool 'ai_visibility_check' for single-entity checks but does not explicitly name alternatives like 'compare_entities' or state when not to use this tool, so it falls short of full exclusion guidance.

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

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

The description discloses important behavioral traits beyond annotations: it fans out to external services, has a potential 5-30 second latency for new versions, and degrades gracefully with partial failures via `sources_failed`. This is rich contextual information that the annotations (readOnly, idempotent, openWorld) do not capture.

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 every sentence earns its place: purpose, when to use, return format, ecosystem scope, and failure behavior are all covered without redundancy. The structure uses dashes and semicolons to group related information efficiently, and it is front-loaded with the core purpose.

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

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

There is no output schema, so the description takes on the full burden of explaining return values: it lists the exact summary block fields, advisory details, links, and alternative versions. It also covers edge cases (non-NPM packages, timeouts, partial failures), making the description complete for a tool of this complexity.

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

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

The input schema already documents both parameters thoroughly (package name, version with default behavior). The description adds context about what the package name is accepted for (scoped packages) but that is already in the schema. The baseline of 3 applies because schema coverage is 100% and the description does not need to compensate.

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 a specific composite purpose: "Composite 'should I add this npm package to my project' check in ONE call" and elaborates on the exact data sources (deps.dev and bundlephobia) and what they provide. It distinguishes itself from sibling tools by emphasizing the unified check and the npm ecosystem 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?

Explicit usage guidance is given: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'". It also provides a clear alternative for non-NPM packages: "PyPI / Maven / Cargo / Go fall under deps.dev:version directly", which helps an agent choose between this and other tools.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful context by specifying the return payload (name, summary, record_count, owner/org, Feature Service URL) and the downstream use of the URL. It does not introduce contradictions and provides practical behavioral insight.

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 the core action, and every word earns its place. It efficiently conveys scope, purpose, and follow-up steps without any fluff.

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

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

For a read-only search tool with optional parameters and rich schema, the description is complete. It covers what the tool returns, how to use the result, and the domain, making it self-sufficient even without an output schema.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds value by explaining what happens with the returned URL (pass to query_layer/layer_info), but it does not add new semantics to the input parameters themselves, staying at 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 searches Fauquier County GIS open geospatial datasets by keyword, with a specific list of example datasets and the resource scope. It distinguishes itself by describing the return of a Feature Service URL to be used with query_layer/layer_info, differentiating it from those downstream tools.

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

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

The description gives clear context for when to use this tool: to find datasets by keyword, and then pass the resulting URL to query_layer or layer_info. It does not explicitly mention when not to use it or alternative search tools, but the workflow is well implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds critical behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged).' It also discloses the return structure (passages with character offsets and similarity scores), which is essential given no output schema.

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 earning its place: core operation, when to use, companion tool, and technical mechanism. No filler or repetition of parameter names. Front-loaded with the most important information.

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

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

The description covers input source, output format (top-N passages with offsets and similarity scores), algorithmic details, truncation behavior, and usage workflow. For a tool with no output schema, it fully explains return values and edge case (200K cap).

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

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

Schema description coverage is 100%, with all three parameters described (text, query, limit). The description adds context about text provenance ('the text you already pulled (e.g. a SEC 10-K body...)') but the schema already documents max length and query examples. A baseline of 3 is appropriate since schema 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 opens with 'Semantic search INSIDE a fetched record,' clearly identifying the verb (search), resource (a fetched record), and scope (inside, not across). It distinguishes from siblings by naming ask_pipeworx_grounded and framing search_within as the pre-processing step for grounding over passages rather than the whole document.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also says 'Pass the text you already pulled,' implying a prerequisite, and pairs with ask_pipeworx_grounded to show the workflow. This gives clear context though it doesn't list exclusions for every sibling, which is acceptable.

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 contradicts the idempotentHint=true annotation. It says 'Returns the new subscription id,' implying each call creates a new subscription, which is not idempotent unless the system deduplicates (not stated). The description otherwise provides useful behavioral context (auth, rate limits, webhook auto-disable), but the contradiction forces a score of 1.

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

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

The description is dense but well-structured, front-loading the core purpose and then branching into supported types and delivery options. Every sentence carries necessary information for a complex tool, though its length is on the higher side.

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

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

For a tool with no output schema, the description covers essential context: authentication, type-specific parameters, delivery channels, caps, and webhook failure auto-disable. It does not fully specify the response structure beyond the subscription ID and one-time webhook secret, but that is a minor gap given the complexity covered.

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 already detailed, but the description adds valuable examples for each type (e.g., sec_8k with items, polymarket_edge with topic, fred_series with series_id) and clarifies the always-on feed channel, which is not represented in the schema. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It also differentiates from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and by mentioning the returned subscription ID.

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

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

The description provides clear usage context: requires a Pipeworx OAuth account, explicitly excludes anonymous/BYO users, lists supported subscription types with examples, and details delivery channels with prerequisites (e.g., phone verification, 10/day cap). It does not explicitly name alternative tools, but the conditions and constraints are clear enough to guide appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavior: that calling with no arguments returns a full spread, passing a topic focuses results, and the output includes tool+argument shape examples. This goes beyond the structured hints and paints a clear picture of what the tool does.

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

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

The description is front-loaded with example queries and the core purpose, then provides details on parameters and usage. It is a single long sentence that packs a lot, but remains dense without being bloated. Slightly long for a quick scan, but every part earns its place.

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

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

For a tool with one optional parameter and no output schema, the description fully covers the input behaviors, the nature of the output (category-bucketed examples with tool+argument shape), and the recommended usage context. It is complete enough for an agent to select and invoke correctly without further clarification.

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 the 'topic' parameter with a description, and the description adds concrete examples of valid values ('finance', 'pharma', 'betting') plus behavior when omitted ('full spread'). This enriches the parameter semantics beyond the bare schema, which already had 100% 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?

The description clearly states the tool returns category-bucketed example questions with the exact tool and argument shape that answers each, drawn from the live catalog. This distinguishes it from siblings like discover_tools or ask_pipeworx by emphasizing its role as an onboarding entry point with concrete example output.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.)'. This provides a clear when-to-use directive and names alternative/related tools, which is strong usage guidance.

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

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

Beyond the annotations, the description discloses key behavioral traits: ownership is enforced, and the row is deactivated rather than deleted, preserving historical events via recent_alerts. This enriches the agent's understanding of side effects and data lifecycle.

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 the main action, and every clause adds unique information. No wasted words or redundant details.

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

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

For a simple tool with one parameter, complete annotations, and no output schema, the description covers all necessary context: the action, a critical prerequisite/constraint, and the consequence of deactivation. No significant gaps remain.

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

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

The schema already fully describes the 'id' parameter with 100% coverage, including its type and provenance ('returned by subscribe'). The description merely mentions 'by id' without adding new meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool cancels a subscription by id, specifying the verb 'cancel' and the resource 'subscription'. It differentiates from siblings like 'subscribe' and 'list_subscriptions' by focusing on the cancellation action.

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

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

The description provides clear context: you use this when you want to cancel a subscription. It includes an important constraint (ownership enforcement) but does not explicitly name alternatives or state when not to use it, earning a 4 rather than 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses vital behavioral details: it uses different pipelines (SEC EDGAR fast path vs. grounded pipeline), returns specific verdict types, and explains the special semantics of 'could_not_verify' and 'unsupported'. This exceeds what annotations alone convey, and there is 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 relatively long but well-structured: it opens with natural-language triggers, then explains usage, then details return values and edge cases. Each sentence serves a purpose, and the organization makes it scannable. A slight deduction for length, but the density of valuable information justifies its size.

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 covers the return format (verdict, value, citation, reasoning) and special error semantics. It explains the two routing paths and the meaning of each verdict type. For a tool of this complexity, the description leaves little ambiguity, making it effectively 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?

The input schema already provides full descriptions for both parameters (100% coverage), which earns a baseline of 3. The description adds value by explaining how 'tolerance_pct' overrides the implied tolerance, gives a concrete use case (hallucination detection with 1–2%), and clarifies the default cap. This supplemental guidance improves parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose with a specific verb ('natural-language claim verification') and resource ('authoritative sources'). It provides multiple natural-language examples that distinguish it from generic search or Q&A tools, and differentiates between financial and non-financial claim handling. This is a precise, non-tautological definition.

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and gives intent examples. It does not explicitly name alternatives or state when not to use it, but it clearly implies the tool is specialized for claim verification rather than general information retrieval. The mention of replacing 4–6 sequential calls adds practical context.

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