Arcgis Indianriver

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond annotations: the default model is free, using Anthropic requires a BYO key with direct billing, and the return shape (per-model {score, confidence, signals, raw_response} + combined view) is disclosed. This enriches the agent's understanding of cost and expected 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: the first states the core function, the second explains model defaults and key requirements, and the third summarizes returns and use cases. It is front-loaded, every sentence adds value, and there is no fluff or repetition.

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 properly covers the return format and practical use cases. It could briefly mention limitations (e.g., model knowledge cutoff or score interpretation), but given the annotations and schema clarity, it provides a sufficient mental model for an agent to select and invoke the tool safely and effectively.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the default model ('Workers AI Llama-3.3-70b (free)') and the relationship between `_apiKey`, the 'anthropic' model, and cost. It also frames `context` as a disambiguator ('helps disambiguate common names'), which goes slightly beyond the schema's description.

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

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

The description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly identifies the tool's function and output, and distinguishes it from siblings like ask_pipeworx by emphasizing visibility scoring and multi-model probing.

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 for use ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass `_apiKey` to include Anthropic. It does not explicitly name alternatives or state when-not-to-use, but the use cases and default-model explanation offer solid 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: it returns structured answers with stable pipeworx:// citation URIs, routes to verified sources, and notes it's 'one fast call' working on all tiers. No contradictions. The description adds meaningful behavioral detail 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 fairly long but every sentence earns its place. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and then provides usage rules, examples, and alternatives. It could be slightly tightened (e.g., some repetition of the 'citations' concept), but overall it is well-structured and informative.

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

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

Given the tool's complexity (6 parameters, all aliases, no output schema, 33+ sibling tools), the description is remarkably complete. It covers when to use, how it works internally, what it returns, and how it differs from siblings. The absence of an output schema is mitigated by stating it returns a structured answer with citations. No gaps remain for the agent to infer.

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 6 parameters, all aliases for the 'question' field, with 100% schema description coverage. The description adds value by providing examples of what kind of questions to ask (e.g., 'current US unemployment rate', 'Apple's latest 10-K') and explaining that the tool fills arguments automatically. This goes beyond the schema's bare-bones 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 starts with a specific directive: 'PREFER OVER WEB SEARCH' and lists a comprehensive set of domains (SEC filings, FDA data, etc.). It clearly states the tool's function: routes questions to a vast array of verified sources and returns structured answers with citations. The purpose is distinct from siblings like ask_pipeworx_grounded and deep_research, which are explicitly mentioned as alternatives.

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

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

The description provides explicit guidance: 'START HERE for most questions', and tells when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). It also gives example queries and lists trigger phrases like 'what is', 'look up', etc. This is exemplary usage guidance.

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

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

Beyond the provided annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial context: the tool is a full working router, falls back to nothing, and is experimental with candidate routing improvements. It also reveals the current state (no active candidate) and that outcomes are compared to the stable router. 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 single, well-structured paragraph of 4 sentences. It is front-loaded, immediately stating the identity and purpose. Every sentence adds value, and there is no unnecessary repetition or verbosity.

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 (beta router with 5,563 tools, candidate routing, experimental edge), the description is complete. It explains the current state, usage, and behavior. No output schema exists, but the description appropriately omits return details since the tool is a question-answering router.

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 all 6 parameters (all aliases for 'question'). The description does not add any parameter-specific meaning, but with full schema coverage, a baseline of 3 is appropriate. No additional semantics needed beyond what the schema provides.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, an identical universal router with the same 5,563 tools and arguments. It distinguishes itself from siblings by explicitly noting the candidate routing improvements and the experimental nature, making the purpose unmistakable.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains that results are compared to the stable router, and mentions that currently no candidate is active, so it matches ask_pipeworx exactly. This tells the agent when to prefer 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 already declare readOnlyHint, idempotentHint, destructiveHint=false, so the safety profile is clear. The description adds significant behavioral context: the extraction-only guarantee, the exact refusal reasons, and the cost tradeoff (one extra LLM call). It doesn't describe what happens if the tool is called with an invalid alias or network errors, but given annotation coverage, a 4 is appropriate.

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 value proposition, then efficiently explains the mechanism, return format, refusal reasons, and when-not-to-use. Every sentence adds unique information, and the cost tradeoff is stated upfront. No wasted words.

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

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

For a complex tool (6 params, many aliases), the description thoroughly covers the purpose, usage conditions, behavioral guarantees, refusal modes, and tradeoffs. The only missing element is what happens with the multiple parameter aliases if more than one is provided (e.g., precedence or conflict handling). However, the description doesn't need to replicate the return schema since no output schema is provided, but it does explain the return structure inline. A 4 reflects strong coverage with a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents the `question` parameter and its aliases. The description adds no semantics beyond what the schema says—it does not specify the expected format, length limits, or example queries. With full schema coverage, baseline 3 is correct.

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 and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly distinguishes this tool from its sibling `ask_pipeworx` by highlighting the grounded extraction vs. a casual lookup, and describes the unique refusal behavior.

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

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

Provides explicit guidance on when to use this tool (high-stakes reads, when answers will be quoted or acted on, e.g., financial verdicts, legal claims) and when not to ('prefer ask_pipeworx for casual lookups'). It also enumerates refusal reasons, making the decision boundary crystal 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 flag readOnly/idempotent, and the description goes well beyond them, disclosing resolver confidence levels, blocking statuses (low_confidence_match, market_closed_or_inactive), illiquid-spread flags, GDELT fallback fields, and cancellation-rule risk. No contradiction with annotations.

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

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

The description is long but organized into bolded sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, SAFETY, RESOLUTION-RULE RISK) and front-loaded with the core purpose. Each section adds operational value for a tool with no output schema.

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

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

Given the tool's complexity and absence of an output schema, the description covers inputs, resolution contract, fan-out categories, response shapes, statuses, and safety, giving an agent nearly everything needed to invoke and trust 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?

Schema coverage is 100%, but the description significantly enriches each parameter with accepted input formats, quick/thorough depth semantics, and include_raw payload-size tradeoffs, plus fan-out and response-shape context.

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

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

The description leads with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools by emphasizing the one-call fan-out and market-vs-model comparison, and gives concrete use cases ('should I bet on X').

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 the tool ('Use for "should I bet on X"...') and includes classifier/fan-out examples. However, it doesn't give explicit when-not conditions or name alternatives like polymarket_edges or validate_claim, so it stops short of a 5.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), correct handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradiction with annotations.

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

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

The description is dense but every sentence carries useful information—examples, preference guidance, data-source details, and result behavior. It could be restructured into bullet points for readability, but it is not padded or redundant.

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

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

Despite having no output schema, the description clearly indicates what the tool returns (paired data with citation URIs, sorted results) and covers important behavioral nuances (fiscal-year handling, entity types). Given the tool's moderately complex scope, this description is sufficiently complete for an AI agent to select and 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?

Schema description coverage is 100% for both parameters, so the baseline is 3. The description adds meaningful semantics by explaining what 'type' values do (company pulls financial data, drug pulls FAERS/trial counts) and clarifies accepted value formats for 'values'. This goes beyond the schema's basic 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 explicitly states the tool performs side-by-side comparisons of 2–5 companies or drugs in a single parallel call, with concrete query examples like 'X vs Y' and 'which is bigger'. It also distinguishes itself from sequential single-pack lookups, referencing a clear alternative pattern.

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 an explicit preference rule: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides a clear usage context via natural-language query examples, making it obvious when to invoke this tool versus alternatives.

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

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

The description goes far beyond annotations, detailing account/auth needs, parallel decomposition, response structure (findings with evidence, confidence, gaps, contradictions), time expectations (15-60s, thorough ~90s), citation resolvability, and semantic excerpting. Annotations already declare readOnlyHint=true, and the description aligns with no contradictions.

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

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

The description is quite long (around 400 words) and somewhat stream-of-consciousness. While all information is valuable for a complex tool, it could be more concise and better structured (e.g., bullet points or clearer sections). Every sentence earns its place, but length reduces readability.

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

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

Given the tool's complexity (2 parameters, no output schema), the description provides thorough coverage: prerequisites, alternatives, depth behaviors, return format, time expectations, and caveats. It compensates fully for missing output schema by detailing the findings packet structure and special features like gap recovery and contradiction scanning.

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

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

Schema coverage is 100%, but the description adds critical meaning: explains depth enum values in detail ('quick=3, standard=5 with gap-recovery hop, thorough=8 with follow-up') and notes that standard/thorough return contradictions. For question, it confirms natural language and multi-part suitability, going beyond the schema's minimal description.

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

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

The description clearly states it performs 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, decomposing questions into facets and routing to tools in parallel. It distinguishes itself from siblings by explicitly naming ask_pipeworx and describing use cases, making the purpose unmistakable.

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

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

The description provides explicit guidance: 'Best for broad/multi-part questions over structured data', then contrasts with 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'. It also specifies account requirements and depth tiers, making when-to-use and when-not-to-use extremely 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, so safety is clear. The description adds valuable behavioral context: it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and guarantees 'no second schema lookup needed,' which manages expectations about output completeness and reusability. It doesn't mention latencies or edge cases, but for a read-only discovery tool this is sufficient.

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

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

The description is concise yet packed with essentials: purpose, usage timing, domain list, return behavior, and call-directly guarantee. Each sentence contributes meaning, and the structure front-loads the core function before expanding on details. It is an exemplar of efficient, well-organized tool documentation.

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 conceptually simple (a search-like discovery endpoint with one required param), and the description covers its operation thoroughly: what it returns (top-N tools with schemas and examples), when to use it, and the fact that no further lookup is needed. Without an output schema, the description shoulders the burden of explaining results, which it does adequately. The schema handles the rest, making the overall definition complete.

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

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

Schema description coverage is 100%, with each parameter documented (query, limit, and aliases). The description repeats the alias behavior already present in the schema ('Accepts task, q, description, search as aliases') without adding new semantic depth. Since the schema fully explains parameter meaning and examples are provided there, the description adds no extra value beyond the 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's function: 'Find tools by describing the data or task.' It specifies the resource (tools), the action (discover/browse/search), and enumerates supported domains (SEC filings, financials, FDA drugs, etc.), distinguishing it from the many domain-specific sibling tools. It also explicitly positions it as a meta-tool ('Call this FIRST'), which separates it from tools that perform direct data queries.

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

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

The description gives explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It outlines the exact scenarios for invocation and notes that results are ready to call directly, implying the subsequent step. While it doesn't state when-not-to-use, the positive guidance is strong and unmistakable.

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), the description discloses valuable behavioral details: it fans out across multiple sources in parallel, returns specific fields (e.g., recent_filings with URIs), handles patent API sunset with soft-fail, and uses a GDELT→GNews fallback. This significantly enriches understanding beyond structured 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 information-dense but well-structured, front-loaded with user intents, then the core function, then output details, then input requirements. Every sentence adds value, and the length is justified by the tool's multi-source complexity. No fluff or repetition.

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

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

Given no output schema, the description thoroughly covers return fields, data sources, behavior on failures, and input constraints. It includes everything an agent needs to decide when to invoke and what to expect, making the tool fully contextualized.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds concrete examples ('AAPL', '0000320193'), explains the zero-padded CIK format, and reinforces the 'names not supported' limitation, which directly helps the agent select and format parameters. It does not introduce new parameter semantics but provides practical context above 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 provides a 'full cross-source profile of a US public company in ONE parallel call' with multiple example phrasings like 'tell me about X' and 'research Acme'. It distinguishes itself from siblings by explicitly recommending it over chained single-pack lookups and by referencing 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?

Explicit usage guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clearly states what it cannot do ('names not supported') and directs to resolve_entity, making the when-to-use vs alternatives very 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 destructiveHint=true and idempotentHint=true. The description reinforces the destructive behavior ('Delete') and adds context about clearing sensitive data, but doesn't disclose additional side effects beyond what annotations provide. This adds some value, so a 4 is appropriate.

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 short sentences: purpose, usage conditions, and a pointer to related tools. No fluff, front-loaded.

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

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

Given the simple one-parameter schema, destructive annotation, and clear usage guidance, the description fully equips an agent to select and invoke the tool correctly. No output schema is needed.

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

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

Schema coverage is 100% with a single 'key' parameter described as 'Memory key to delete'. The description simply says 'by key' without adding extra semantics, so baseline 3 applies.

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

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

The description uses the specific verb 'Delete' with the resource 'previously stored memory by key', clearly distinguishing it from sibling tools like remember and recall by specifying the deletion 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?

It provides explicit conditions for when to use ('context is stale, task is done, or clear sensitive data') and points to companion tools ('Pair with remember and recall'), fulfilling the when/alternatives criteria.

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

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

Annotations already cover safety (readOnly, openWorld, idempotent, non-destructive). The description adds behavioral context by explaining the process (fetches the page, extracts title/description/key links) and the output (single text blob in llms.txt markdown), which goes beyond what annotations provide.

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, each earning its place: purpose, process, output format, and use cases. It is front-loaded with the main action and avoids redundancy or fluff.

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

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

Given the tool's simplicity (2 params, no output schema), the description is fully complete. It covers input (URL), process, output, and use cases, and the annotations cover safety. No meaningful 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% for both parameters (url and max_links). The description does not add meaningful parameter details beyond the schema, only referencing the URL implicitly and the output format. Baseline of 3 is appropriate since schema 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 states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes from sibling tools by focusing on generation for AI crawlers and providing three concrete use cases (client indexing, personal projects, competitor auditing).

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' section gives explicit contexts when this tool is appropriate, including client indexing, drafting for your own project, and auditing. It does not explicitly state when not to use or name alternative tools, but the use cases provide clear guidance for an agent.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by explicitly listing the return contents (fields, geometry type, record count, capabilities), giving the agent concrete expectations about what it will receive. It does not mention any caveats like potential performance issues, but that is acceptable for a read-only schema 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 a single, well-structured sentence that front-loads the primary purpose ('Get an ArcGIS Feature/Map Service layer's schema') and immediately lists the included items. Every word serves a purpose, with no redundancy or filler.

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

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

Given the tool is simple (one parameter, no output schema), the description fully covers what it does and what it returns. The parameter is adequately documented in the schema, and the description lists all expected output components, making the tool's behavior clear without an explicit 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 schema description already fully covers the 'url' parameter, and the tool description only restates 'by url' without adding new details about format, constraints, or usage. With 100% schema coverage, the baseline is 3, and no additional semantic value is provided here.

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

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

The description uses a specific action verb ('Get') and identifies the exact resource ('ArcGIS Feature/Map Service layer's schema') along with the key details returned (fields, geometry type, record count, capabilities). This clearly distinguishes it from the sibling tool 'query_layer' which is about data retrieval rather than schema inspection.

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 makes the tool's purpose obvious — obtaining schema information by providing a layer URL. It implies the tool should be used when needing layer metadata rather than data, but it does not explicitly contrast it with 'query_layer' or other alternatives. However, the context is clear enough and no misconceptions are introduced.

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=true, so the safety profile is covered. The description adds value by disclosing that the response contains specific fields and is scoped to the caller's active subscriptions, enhancing transparency 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?

Two concise sentences cover purpose, scope, output fields, and use cases. No redundant information; 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 simplicity (one optional parameter, strong annotations, no output schema), the description is complete: it states the output fields, usage context, and default active-only behavior. No significant gaps.

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

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

The schema fully describes the only parameter (include_inactive) with a clear description, and coverage is 100%. The tool description adds no further parameter semantics, so baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with a specific verb, resource, and scope. Also lists the exact return fields, distinguishing it from sibling tools like subscribe/unsubscribe.

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

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

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indicates when to use the tool in workflows. It doesn't explicitly mention exclusions or alternatives, but the context is clear given the sibling tools.

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

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

Adds meaningful behavioral context beyond annotations: daily digest reading, rate limit of 5/day, free/no quota, claim_token workflow for later retrieval. No contradiction with the all-false 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?

Every sentence carries unique, non-redundant information: purpose, use cases, exclusions, token workflow, and rate limits. Well-structured and appropriately front-loaded with the primary action.

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?

Without an output schema, the description still covers valid input types, return token behavior, rate limiting, and intended usage. Provides enough detail for an agent to invoke and follow up correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds value by explaining claim_token usage ('pass it back later... with no other arguments') and message-content guidance (avoid pasting the end-user's prompt), which goes 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?

Clearly states 'Tell the Pipeworx team something is broken, missing, or needs to exist,' identifying a specific verb and resource. It distinguishes itself from sibling tools by scoping feedback to the Pipeworx connection and excluding 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?

Explicitly lists use cases (bug, feature, data_gap, praise) and explains when not to use (other servers' tools). Provides troubleshooting guidance ('Not sure? Pipeworx tool names are the ones this connection lists').

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 behavior. The description enriches this with caching details (5min-1h), data provenance (CF analytics-engine), and privacy assurances (no PII), which are beyond the annotation defaults and add practical context.

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

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

The description is well-structured with a clear lead sentence, a 'Useful for' list, and a closing detail sentence. Every section adds value, though the bulleted list could be slightly tighter without losing meaning.

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

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

For a tool with no output schema and one optional parameter, the description covers the core return components, window options, caching, and use cases. It lacks a formal response structure breakdown, but the information given is sufficient for basic 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?

The input schema fully documents the single 'window' parameter with enum and semantic descriptions, giving a baseline of 3. The description adds extra meaning by explaining how shorter versus longer windows map to 'hot now' versus 'steady-state demand' and by noting caching varies by window.

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 explicitly states the tool returns trending usage data ('top tools, top packs, and total call volume') over configurable windows, and the 'Useful for' list clarifies its distinct role from sibling tools like discover_tools by focusing on real-time agent call patterns.

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?

Clear 'Useful for' guidance is provided with three specific scenarios (discovering hot sources, confirming canonical tool choice, aligning with agent needs). However, it does not explicitly name alternative tools or state when not to use it, so it stops 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses significant behavioral details: semantic anchor Jaccard threshold, placeholder filtering, partition-check deviation threshold (>3pp), fill-check pricing against live order book depth, and the meaning of realizable_edge_pp <= 0 (do not trade). It also clearly states the response structure, 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?

The description is long but well-structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence provides useful information, but the density could be slightly reduced without losing value. It is appropriately front-loaded with the main purpose and mode selection.

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, no output schema, and two optional parameters, the description covers all necessary aspects: purpose, modes, response fields, filtering logic, fill-check warnings, and cross-references to a related tool. It is complete enough for an agent to select and invoke the tool correctly without additional documentation.

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

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

Schema descriptions are already present, but the tool description adds substantial meaning: concrete examples of event slugs ('fed-decision-may-2026'), acceptance of full Polymarket URLs, and what topic mode expects ('seed question'). It explains the behavior triggered by each parameter, which the schema alone does not convey.

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+mechanism: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes two modes (event and topic) and mentions a no-arg trending scan, which separates it from sibling tools that might simply report prices or edges.

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

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

Provides explicit instructions on when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It also directs users to polymarket_fill_risk for custom sizing. However, it does not explicitly compare against sibling tools like polymarket_edges or polymarket_edge_tracker, so the guidance is not fully exhaustive.

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

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

Beyond the readOnly/idempotent annotations, the description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), slippage adjustment, Kelly caps, and detailed diagnostics for empty segments. It also explains the unreliable Fed signal and the 24h-move warning, providing rich behavioral context without contradicting 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 an extremely dense, multi-paragraph wall of text with extensive implementation details (e.g., per-sport alpha values, specific Run 8 gate relaxations) that could be pruned for agent usability. While it has clear headings and segments, it is not appropriately sized and burdens the agent with far more detail than needed.

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 comprehensively details the response structure: by_segment with three model families, fed_candidates/fed_note, and _diagnostics with funnel counters. It explains filtering knobs, caching, and why segments may be empty, making the tool behavior fully predictable for 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?

The input schema already documents all 9 parameters with detailed descriptions, giving a baseline of 3. The description adds semantic richness by grouping 'TRADEABLE-EDGE KNOBS,' explaining how min_partition_leg_kelly applies only to per-leg Kelly inside partitions, and clarifying that min_kelly does not filter partition arbs.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' clearly stating the tool's purpose and scope. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by framing itself as a daily discovery scan and describing its three response segments.

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 says it's built for 'what should I bet on today' and notes that agents can discover opportunities 'without paging hundreds of markets,' implying the intended use case. It also provides exclusions ('Fed bets surface here, excluded from ranking') and warns when edges may already be priced in, but it does not explicitly name alternative tools or when-not-to-use scenarios relative to 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 readOnly, idempotent, non-destructive, and open-world hints. The description goes far beyond this by detailing exact response structure (tracked[], expired[], snapshot_dates[]), explaining data gaps ('snapshots are written on cache-miss'), and disclosing limitations (60-day TTL, daily closes not intraday). This is exceptional behavioral disclosure and adds significant value.

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 efficiently organized with labels (Args:, RESPONSE:, LIMITS:) and dense, purposeful content. Every sentence contributes to understanding output semantics or constraints. It could be trimmed slightly, but the complexity of the tool justifies the length.

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

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

With no output schema, the description fully carries the burden of explaining return values. It describes each field (tracked, expired, snapshot_dates), provides interpretations (trend, decay_pp_per_day, median lifespan), and lists limitations. This is a complete and self-sufficient description for an agent to use the tool correctly.

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

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

Schema coverage is 100%: both days and window have descriptions. The description restates the same info (default 14, max 30; window family default 1wk) without adding new semantics. Since the baseline for high schema coverage is 3 and the description adds no meaningful param detail beyond the schema, a 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a concrete question ('how long has this edge existed and is it shrinking?') and clearly distinguishes itself from the sibling polymarket_edges tool by focusing on historical persistence/decay rather than current edge levels.

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 strong usage context by contrasting fresh vs. old edges ('a 3-week-old wide edge is different trades') and explaining that expired opportunities reveal competition. It does not explicitly name alternative tools or state when NOT to use it, but the framing makes the intended scenario clear enough for an agent to choose this over polymarket_edges.

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, idempotent, non-destructive), the description discloses detailed behavior: it 'walks the ladder', returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and verdict, and explains how size_usd is interpreted differently in single-market vs basket mode. It also surfaces risk behaviors like partial fills and 'forced_directional_risk,' which are not evident from annotations alone.

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 dense paragraph, but it is logically organized by mode (SINGLE-MARKET and BASKET) and front-loaded with the core purpose. Every sentence carries substantive information, though the length and use of inline headings could be slightly more scannable. It is not bloated, but a more structured layout would improve readability.

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

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

Given the tool's complexity (two modes, conditional parameters), the description is remarkably complete. It enumerates return fields for each mode, explains edge cases (thin_legs, max_clean_notional_usd, forced_directional_risk), and connects to real-world usage context. There is no output schema, so the description's detailed return-value list fulfills that need, making this highly complete.

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

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

The schema provides complete per-parameter descriptions, but the tool description adds substantial semantics: it explains that `market` and `event` select mutually exclusive modes, clarifies `side` defaults per mode, and defines `size_usd` as 'max spend on buys, target proceeds on sells' (single-market) versus 'settlement notional S' (basket). This goes well beyond the schema and is essential for correct invocation.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly states a specific verb+resource and distinguishes this from sibling tools like polymarket_arbitrage and polymarket_edges. It then elaborates on two distinct modes (single-market and basket), each with explicit goals, making the tool's 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?

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills convert arb into unhedged directional risk), clearly defining when to use this tool versus alternatives.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, but the description goes far beyond: it details the compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and response shape. This rich behavioral disclosure sets clear expectations and aligns perfectly 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 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS' labels, and every sentence adds substantive detail. While it is verbose, the density of critical information justifies the length, and the front-loaded core definition ensures immediate orientation.

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

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

Given the tool's complexity, the description covers all essential aspects: input modes, response format, safety warnings, and interpretation guidance. With no output schema present, the explicit description of response fields and compatibility flags provides complete context for an agent to select and interpret results 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 covers all three parameters with descriptions, so the baseline is 3. The description adds significant meaning by explaining the two modes, how explicit parameters override topic-mapped ones, and the exact list of topic shortcuts, making parameter usage far clearer than the schema alone.

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

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

The description immediately states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with a specific verb and resource. It also differentiates from siblings by explaining its unique dual-mode operation and safety fields, making the purpose unmistakable.

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

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

The description provides clear usage context for both modes (topic shortcuts vs explicit tickers) and warns that pre-mapped topics often return compatibility warnings, effectively conveying when the tool is appropriate. It does not explicitly name alternative sibling tools, but the guidance is strong enough to prevent misuse.

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

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

Annotations already indicate a safe read operation (readOnlyHint, destructiveHint=false, idempotentHint). The description adds behavioral value by stating it returns attribute rows and geometry, and it offers the sampling idiom. The default limit and max limit are in schema, so description doesn't need to repeat. This is solid coverage 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?

Three sentences: purpose, parameter list, and usage tip. Every sentence earns its place with no fluff. Front-loaded with the primary action.

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 effectively communicates return shape (attribute rows and geometry). It also gives sample usage patterns and parameter formatting. For a moderate-complexity tool with good schema coverage, this is complete.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds slight semantic value by noting the URL comes from search_datasets and clarifies the SQL-like nature of where and comma-separated out_fields, though these are already in schema. The extra hint about sourcing the URL nudges it to a 4.

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

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

The description clearly states the tool queries an ArcGIS Feature/Map Service layer by URL, with a specific verb (Query) and resource (layer). It distinguishes from siblings like layer_info (metadata) and search_datasets (finding datasets), and even references search_datasets as the URL source.

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 clear context on when to use the tool (after obtaining URL from search_datasets) and gives a practical sampling tip (where='1=1' + out_fields='*'). However, it does not explicitly mention alternatives or when not to use it, so it stops short of a 5.

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

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 key behavioral context beyond annotations by explaining that stored values are scoped to the user's identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys, adding transparency about its data scoping 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?

Three sentences, each with a distinct purpose: core action, usage scenario, and scoping semantics. Front-loaded with the primary verb and resource, no redundant phrases, and every sentence adds value.

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

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

For a simple lookup tool with one optional parameter and clear annotations, the description covers the essential aspects: purpose, usage, scoping, and related tools. A minor gap is the lack of mention of return behavior when a key is missing, but this is a simple edge case and the tool's behavior is otherwise well-specified.

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 describes the key parameter (100% coverage), so baseline is 3. The description goes beyond the schema by providing real-world examples of key contents (target ticker, address, research notes) and explaining the relationship to remember/forget, which enriches parameter understanding.

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

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

The description clearly states the tool's action: retrieve a value saved via remember, or list all saved keys when the key argument is omitted. It distinguishes itself from sibling tools remember and forget by framing recall as the retrieval counterpart.

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

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

The description gives explicit usage context: use this tool to look up previously stored context without re-deriving it, and it pairs the tool with remember (save) and forget (delete). It doesn't explicitly state when not to use it, but the guidance is clear enough for an agent to decide.

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, and destructiveHint=false, covering the safety profile. The description adds valuable context beyond these: it explains that mark_read:true changes state (flagging events as read so later calls only show newer ones), and it discloses the return payload structure (source, citation_uri, raw event payload). It also notes the feed is persisted. This is solid additional transparency without contradicting 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 three sentences, front-loaded with the core purpose. It packs in return-value details, filtering examples, mark_read behavior, polling note, and an alternative endpoint without being bloated. It's efficient, though slightly dense; a bit of pruning could make it even sharper, so it lands at 4.

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 5 parameters and no output schema, the description carries a heavy load and handles it well. It explicitly describes the return fields (source, citation_uri, raw payload), explain filtering options with examples, clarifies mark_read side-effects, assures polling is fine, and offers an alternative access path for scripts/dashboards. This is a complete description for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by giving a concrete type example ('sec_8k'), specifying the ISO timestamp format for 'since', and most importantly explaining the semantics of mark_read: 'flag returned events read so the next call only shows newer ones.' This goes beyond the schema's simple field descriptions, earning a 4.

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

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

The description opens with a specific verb+resource: 'Pull fired events from your subscription feed.' It clearly names the resource (subscription feed alerts) and the action (pull/return), distinguishing it from sibling tools like list_subscriptions (which lists subscriptions themselves) and recent_changes (which likely tracks broader data changes). The scope is 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 gives clear usage context: 'Polls work fine' indicates suitability for polling, and it points to an alternative HTTP endpoint (GET registry.pipeworx.io/alerts.json) for scripts/dashboards. It does not explicitly name when to avoid this tool or compare to specific sibling tools, so it loses a point for missing explicit exclusions/alternative tool 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 goes beyond the readOnly/idempotent annotations by disclosing operational details: it fans out to multiple APIs, uses GDELT→GNews fallback on rate limits or 5xx, and notes that USPTO 'soft-fails until reactivated' due to the PatentsView API sunset. It also mentions the return structure (changes[], total_changes, citation URIs). These are valuable behavioral insights not captured in annotations.

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

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

The description is dense but well-structured. It opens with natural-language example queries, then gives a concise summary, followed by operational details (sources, fallback), parameter guidance, and an explicit alternative. Every sentence adds value, though it is longer than strictly necessary. The structure helps readability.

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

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

There is no output schema, but the description preemptively explains the return shape: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' It also covers failure modes (GDELT to GNews fallback, USPTO soft-fail), making it complete for a read-only monitoring tool. The explicit comparison with entity_profile covers the sibling context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantic guidance beyond the schema: it explains `since` accepts ISO or relative shorthand with concrete examples and recommends '30d' or '1m' for monitoring. It also clarifies that `value` can be a ticker or CIK. This justifies a 4 rather than 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 uses a specific verb-resource pair: 'change feed for a company' and lists concrete sources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from the sibling tool by explicitly saying 'Use entity_profile instead when you want the static profile...', making the purpose unmistakable.

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

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

It gives explicit guidance on when to use this tool vs. alternatives: 'Use entity_profile instead when you want the static profile...' and provides a typical use case: 'Use "30d" or "1m" for typical monitoring.' The description also explains the fan-out behavior, giving context for expected results.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false; the description adds scoping ('scoped by your identifier') and retention details (persistent for authenticated users, 24 hours for anonymous). This provides useful behavioral context beyond the structured 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?

Four sentences, front-loaded with purpose, and every sentence contributes value (examples, retention policy, sibling tool pairings). No redundancy or filler.

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

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

The description covers purpose, usage, storage scope, retention, and relationships to sibling tools. With no output schema, return value explanation is unnecessary. Slight gap: doesn't mention overwrite behavior, but idempotentHint already implies it, so completeness is strong.

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

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

The input schema already describes both parameters with examples and 100% coverage. The description adds the 'key-value pair' context but does not elaborate on parameter formatting or edge cases, leaving semantics primarily to the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and gives concrete examples (resolved ticker, target address). It distinguishes from sibling tools by explicitly naming recall and forget as retrieval and deletion counterparts.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and covers context like authenticated vs anonymous sessions. Directly references alternative tools: 'Pair with recall to retrieve later, forget to delete.'

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes well beyond by detailing internal cascading lookups, source labeling of identifiers, explicit declaration of unresolved identifiers, graceful degradation when GLEIF or OpenFIGI are unavailable, and the ability to resolve ISINs via LEI mapping. This comprehensive behavioral disclosure adds significant value beyond the annotations and contains no contradictions.

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

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

The description front-loads with example queries and a clear one-line purpose, then structures details by entity type. It is somewhat verbose (over 300 words), with thorough explanations that are valuable but could be trimmed. For instance, the detailed note about LEI/FIGI degradation could be condensed. Every sentence serves a purpose, but conciseness could be improved without losing meaning.

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

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

Given the tool's complexity (two parameters, no output schema), the description covers input behavior thoroughly for both entity types, explains fallback scenarios, and hints at the output structure (identifiers with source labels, unresolved list). It does not explicitly describe a JSON return format, but the behavioral coverage is sufficient for an agent to understand what the tool produces. With no output schema, a slightly more structured output description would elevate completeness to a 5.

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

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

Although schema description coverage is 100%, the description enriches each parameter with concrete examples and behavioral nuance. For 'type', it explains that 'company' yields a cross-source identity spine with enrichment details; for 'value', it specifies that for companies it accepts ticker, CIK, ISIN, or name, and explains the special ISIN-to-LEI mapping for non-US entities. This goes far beyond the schema's terse 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 concrete example queries ('What's the ticker for…', 'find the CIK for…'), immediately establishing the verb 'resolve' and resource 'entity name to identifier'. It explicitly states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input', which distinguishes it from sibling research and query tools. The supported types (company, drug) and identifier details (CIK, ticker, LEI, FIGI, RxCUI) leave no ambiguity about the tool's purpose.

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

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

The description includes the directive 'Use FIRST whenever you have a name but need an ID', providing clear timing for invocation. It explains that the tool replaces 2-3 manual lookups, implying efficiency benefits. However, it does not explicitly state when not to use it (e.g., if an ID is already known) or name specific alternative tools, which would further aid agent decision-making.

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?

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds extra context: it reveals the tool internally calls ai_visibility_check, ranks by score, and returns a structured result ('score, confidence, signal density per entity'). This goes beyond the annotations' safety profile, though it doesn't discuss potential rate limits or error 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, front-loaded with the core purpose, then method, use case, and output format. Every sentence adds value with no fluff or repetition. It is concise yet comprehensive.

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 no output schema, but the description provides the return format ('ranked list with score, confidence, signal density per entity'). It also explains the input in the context of a use case, and safety is covered by annotations. For a comparison tool with clear schema and annotations, this is complete.

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

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

The input schema covers all parameters with descriptions for each (100% coverage). The tool description doesn't add much beyond what's already in the schema, but it does reinforce the 'first entry as subject' concept for entities in the use-case phrasing, which is also in the schema. Since the schema carries the load, 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 states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities). It also distinguishes itself from the sibling tool ai_visibility_check by explicitly mentioning it probes each entity with that tool, making the multi-entity nature obvious.

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

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

The description provides a clear use case: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use this tool (when comparing multiple entities) versus the single-entity ai_visibility_check, though it doesn't explicitly mention alternatives or when not to use it. This is strong but lacks explicit exclusionary guidance.

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

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

Beyond readOnly/idempotent annotations, the description discloses fan-out behavior, output contents, degraded partial failures, and a 5-30s first-measurement latency with a sources_failed indicator. 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 information-dense; it front-loads the core purpose and then covers outputs, scope, and failure modes. Could be tightened, but every sentence adds relevant context.

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

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

No output schema exists, so the description enumerates the returned summary fields and artifacts, explains NPM-only scope, and addresses failure scenarios. This gives an agent a complete expectation set.

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

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

Schema coverage is 100% for both parameters with clear descriptions. The description reinforces usage but doesn't add significant parameter-level 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 defines the tool as a composite npm package check aggregating deps.dev and bundlephobia data. It explicitly scopes to NPM and differentiates from direct deps.dev usage, making the purpose unmistakable.

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

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

Explicit usage triggers ('is X safe / popular / small') and an exclusion ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly') are provided. It also notes latency and partial-failure behavior, guiding when to expect timing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is well covered. The description adds useful context about return content (name, summary, record_count, owner/org, URL) and downstream tools, but does not disclose potential search behaviors like pattern matching or result limits beyond schema defaults.

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 scope, and every clause provides value including the return format and downstream tool references. There is no redundancy or fluff.

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

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

Despite lacking an output schema, the description explains exactly what the tool returns and how to proceed with the results, which is essential for an agent. It does not mention pagination, ordering, or potential edge cases in search behavior, but given the annotations and schema, the description is largely sufficient for effective use.

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

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

Schema coverage is 100%, with each parameter (query, limit, org_id) having a clear description. The description adds no new parameter-level semantics beyond indicating that 'keyword' maps to the query parameter; it simply reinforces the top-level purpose rather than enhancing parameter understanding.

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

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

The description clearly states it searches Indian River County GIS open geospatial datasets by keyword, with specific examples like parcels, addresses, and zoning. It also distinguishes itself from siblings by explicitly noting it returns Feature Service URLs intended for use with query_layer and layer_info.

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

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

The description provides clear context that this is a discovery tool for finding datasets and returning URLs for subsequent queries, which guides the agent on next steps. However, it lacks explicit exclusions or direct comparison to sibling search tools, so it doesn't fully cover 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?

Beyond the readOnly/idempotent annotations, the description discloses concrete behaviors: every passage carries an offset for verification, uses BGE-base-en embeddings with cosine similarity on 500-char overlapping windows, and has a 200K char cap with truncation flagging. There is 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?

Four sentences, front-loaded with the core action, then use case, pairing, and technical spec. Every sentence adds value without redundancy. Highly concise 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?

Even without an output schema, the description covers return format (passages with offsets and similarity scores), algorithm details, limits, and truncation behavior. It fully explains the tool's behavior, use case, and alternatives, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about what the query is for and the 'top-N' notion, but the schema already provides detailed parameter descriptions. No significant new parameter-level meaning is added beyond what the schema states.

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

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

The description opens with 'Semantic search INSIDE a fetched record,' which precisely states the action and resource. It distinguishes itself from siblings by naming ask_pipeworx_grounded as a pairing and clarifying it searches inside already-fetched text, not 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?

It explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also gives an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear, actionable 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 several behavioral traits beyond the annotations: the OAuth requirement, the always-on feed, the 10/day SMS cap, and webhook auto-disable after 10 consecutive failures. It also mentions the one-time webhook signing secret, which is critical side-effect information. No contradictions with annotations exist.

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, starting with the primary purpose and then branching into requirements, types, and delivery. While it is longer than ideal, every sentence adds value and the key information (create action, return value) is front-loaded. The use of semicolons and examples keeps it readable.

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 (5 subscription types, 3 delivery channels, no output schema), the description covers all critical aspects: what it does, auth, types, delivery behavior, and the return value. It even references where to pull the feed (recent_alerts or registry URL), making it self-sufficient for an agent to invoke correctly.

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

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

The schema already covers parameter descriptions at 100%, but the description enriches this with concrete examples for each subscription type (e.g., 'items:["5.02"] = officer change') and delivery channel clarifications. It also explains the difference between the persistent feed and optional email/SMS/webhook delivery, adding semantic depth beyond the schema's per-field 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 'Create a proactive monitoring subscription to a live-data event stream,' clearly stating the verb and resource. It also specifies the return value ('Returns the new subscription id'), distinguishing it from sibling tools like list_subscriptions and unsubscribe. This makes the tool's purpose unambiguous.

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

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

The description establishes clear context for when to use the tool: when a user with a Pipeworx OAuth account needs to monitor live data events. It lists supported subscription types and delivery channels, giving the agent the necessary decision framework. It does not explicitly name alternatives, but the 'Requires a Pipeworx OAuth account' clause sets expectations for usage prerequisites.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds useful behavioral context about the return format (category-bucketed example questions with tool and argument shapes) and how the optional topic parameter changes the result, without conflicting with annotations.

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

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

The description is dense and front-loaded with user-like queries and a clear purpose statement. It is lengthy due to enumerating categories and listing meta-tools, but every part contributes to understanding usage and output; no filler is present.

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

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

Despite having no output schema, the description fully covers the tool's purpose, when to use it, how to call it (with and without the optional parameter), what it returns, and how it relates to sibling tools. This is complete for a simple, single-parameter onboarding tool.

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

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

The input schema already provides 100% coverage for the single optional parameter, including allowed values and the instruction to omit for a cross-category spread. The description repeats these examples ('finance', 'pharma', 'betting') but does not add significant new meaning beyond the schema, so the baseline score applies.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what Pipeworx can do, returning category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from sibling tools like discover_tools by emphasizing the live catalog of thousands of tools and the meta-tool learning angle.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on calling with no arguments for a full spread or with a topic to focus. It also names related meta-tools (ask_pipeworx, entity_profile, compare_entities) as things to learn about, giving clear context for when to use this tool.

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

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

Beyond the annotations, the description discloses the crucial behavioral trait that the row is deactivated (soft delete) and that historical events remain accessible via recent_alerts. It also notes ownership enforcement, adding valuable context for the agent.

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

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

Two concise sentences front-load the primary action and then add necessary behavioral details. No filler or redundancy.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, and side effects. It is sufficiently complete for an agent to use 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 already provides a complete description of the single 'id' parameter (including its format and origin). The description adds no extra meaning beyond 'by id', so the baseline of 3 for high schema coverage 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 ('Cancel a subscription by id') with a specific verb and resource, and it is distinct from related sibling tools like subscribe and list_subscriptions. No ambiguity about what the tool does.

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

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

The description provides clear context: ownership is enforced and cancellation deactivates rather than deletes. It implies usage for canceling subscriptions but does not explicitly contrast with alternatives or mention when not to use it. Acceptable guidance with room for more 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?

The description discloses far more than the annotations: it explains the SEC EDGAR fast path vs the grounded pipeline, defines each verdict (especially could_not_verify and unsupported), clarifies that could_not_verify is not evidence, and mentions the verification_error{stage,detail} detail. This is outstanding transparency that sets clear caller expectations.

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

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

The description is long but information-dense, front-loading with user intents and usage guidance. Every sentence carries distinct value, and the structure (use case, fast path vs grounded, return values, important caveats) is logical. It could be tightened slightly, but the complexity justifies the length.

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

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

With no output schema, the description fully covers return values (verdict options, actual value with citation, reasoning), clarifies error semantics, and explains the two processing paths. Given the tool's complexity, this is a thorough and complete description that leaves no critical gaps.

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

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

The input schema already provides 100% coverage for both parameters, including tolerance_pct range and default behavior. The description adds context about the claim processing but does not materially expand the meaning of the parameters beyond what the schema states. A baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with explicit user intents (e.g., 'fact check', 'verify the claim'), a specific verb+resource ('verify claim against authoritative sources'), and a distinct two-path architecture that separates it from generic Q&A siblings. It goes well beyond a mere restatement of the name.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and even distinguishes between company-financial claims and other claims, giving clear sub-guidelines. However, it does not explicitly name alternative tools or provide when-not-to-use exclusions, which would be needed for a 5.

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