Arcgis Pflugerville

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

Beyond the read-only/idempotent annotations, the description adds that Anthropic calls require a BYO key and direct payment, and it details the per-model return structure. This is valuable behavioral context regarding cost and external API usage, justifying a 4.

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 tight sentences: action, model/cost specifics, and return format plus use cases. Every sentence earns its place with no fluff or repetition, making it 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?

For a read-only probe tool with four documented parameters and no output schema, the description covers what it does, how to invoke it, cost implications, return structure, and suitable scenarios. Minor gaps like undefined 'signals' and no rate limits keep it from 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by naming the default model (Workers AI Llama-3.3-70b) and explaining that `_apiKey` is for optionally probing Anthropic with direct cost implications, pushing 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 probes one or more LLMs and scores visibility (0-100) per model, which is a specific verb+resource+output. It does not explicitly distinguish from sibling tools like scan_competitor_ai_presence, so it falls short of a 5.

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

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

It provides concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and clarifies model selection and API key usage. While it gives clear context, it lacks explicit when-not-to-use or alternative tool references, matching a 4.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond these: it acts as a router/filler, returns structured answers with pipeworx:// citations, works on every tier, and is a single fast call. This goes beyond the safety annotations and gives a clear mental model of the tool's operation 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 front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and then systematically covers routing, examples, and alternatives. It is fairly long but each section adds distinct value. However, there is some redundancy in repeatedly emphasizing 'prefer' and 'start here', and the list of example domains could be slightly more compact. Still, it remains well organized and not overly verbose for a tool that is meant to be the default entry point.

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

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

For a tool that serves as a universal entry point to thousands of sources, the description is exceptionally complete. It gives a clear picture of the tool's scope, examples of appropriate queries, criteria for stepping up to more specialized siblings, and even notes the citation format in the response. There is no output schema, but the description mentions the structured answer and citation URIs, providing sufficient context for an agent to understand what to expect when invoking the tool.

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

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

The schema has 100% coverage with all aliases (question, q, text, input, query, prompt) documented and clearly stating they are interchangeable. The description goes further by providing multiple representative example questions (e.g., 'current US unemployment rate', 'Apple's latest 10-K', 'patents Tesla was granted last month') which effectively illustrate the expected natural-language input range, adding meaning beyond the schema's 'Alias for question' and confirming the flexible alias usage.

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's function: routing questions to 5,529 tools across 1,455 verified sources and returning structured answers with stable citation URIs. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research and describing their different use cases, establishing this as the default entry point.

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

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

The description provides explicit guidance on when to use this tool (any factual question about real-world entities, events, numbers) and when to prefer alternatives (hallucination-resistant answers -> ask_pipeworx_grounded; broad/multi-part questions -> deep_research). It also addresses breaking news and explicitly says to use it even when web search could answer, 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 provide read-only, open-world, idempotent, and non-destructive hints. The description adds valuable context about the beta status, current state (no active candidate), and that it currently matches ask_pipeworx exactly, which goes beyond the annotations. It does not contradict 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 four sentences, each providing a specific detail: beta status, identical interface, usage guidance, and confirmation it is a full router. It is concise yet informative, though slightly longer than a two-sentence ideal.

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 explains the experimental nature, current state, relationship to ask_pipeworx, and confirms it is a working router. It doesn't describe the response shape, but relies on 'same response shape' as ask_pipeworx, which is acceptable given the context. No output schema, but the description sufficiently covers what the tool does.

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

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

Schema description coverage is 100% with all aliases documented. The description only mentions 'same arguments' as ask_pipeworx, adding no new parameter semantics. Baseline 3 is appropriate since the schema fully covers parameter meaning.

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

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

The description clearly identifies ask_pipeworx_beta as a beta version of ask_pipeworx with identical tools, arguments, and response shape, but with experimental routing improvements. It distinguishes from the stable ask_pipeworx by emphasizing the candidate routing improvements and its role as 'the experimental edge'.

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

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

The description states to use it 'exactly like ask_pipeworx when you want the newest routing', providing a clear when-to-use condition. However, it does not explicitly mention when not to use it or compare with other alternative tools like ask_pipeworx_grounded, so it lacks explicit exclusions.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral traits: it returns a refusal with specific refusal_reason values when data doesn't directly answer, includes evidence verbatim quotes, and details the exact success/refusal response shapes. It also mentions the extra LLM call cost, adding valuable context not covered by 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 moderately long but every sentence contributes unique information—purpose, mechanism, response formats, usage guidance, and cost trade-off. It is front-loaded with the key differentiator 'Hallucination-resistant' and structured clearly (success vs refusal). It earns a 4 for being dense without redundancy.

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

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

Despite having no output schema, the description thoroughly explains the return values on success and failure, including the exact refusal reasons and the evidence mechanism. It covers routing, usage context, cost implications, and compares to the sibling tool ask_pipeworx, making it complete for the tool's complexity.

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

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

The input schema already provides 100% coverage of all 6 parameters (question and its aliases), so the description does not need to compensate. The description adds that the question should be in natural language and is the sole input, but this does not go meaningfully beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states the tool's purpose and key differentiator. It specifies the mechanism (routing to tools, fetching data, extracting answers with evidence) and distinguishes it from sibling ask_pipeworx by emphasizing groundedness and 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?

The description explicitly states when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete example domains (financial verdicts, legal claims, medical lookups, public statements). It also gives a clear when-not and alternative: 'prefer ask_pipeworx for casual lookups' and notes the additional LLM call cost as justification.

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

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

Even with annotations declaring readOnly, openWorld, idempotent, and non-destructive, the description goes far beyond by disclosing resolver contract details, parent-event extraction, news fallback fields, low-confidence short-circuiting, closed-market handling, wide-spread warnings, and cancellation-rule risks. This adds substantial behavioral context beyond annotations.

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

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

The description is unusually long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It front-loads the core purpose and then systematically covers necessary details. Every section earns its place given the tool's complexity, though a more concise version could be imagined.

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

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

With no output schema, the description thoroughly explains return shapes (result.market, result.analysis, result.evidence), safety statuses, edge cases (low confidence, closed/dead markets, wide spreads), and resolution-rule risks. It also covers fallback behavior for news sources, 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 covers 100% of parameters, so baseline is 3. The description adds value by explaining the market parameter's resolution behavior (slug/URL/question text) and fan-out examples that illustrate depth semantics. While not adding new fields to the schema, it enriches understanding of how parameters drive behavior.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings like polymarket_edges or polymarket_arbitrage by focusing on single-bet research and explicitly lists classifiers and fan-out examples.

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

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

The description provides explicit 'Use for' scenarios ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and gives concrete examples. It lacks explicit when-not-to-use or named alternatives, but the context is clear enough to differentiate from sibling tools.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds rich behavioral detail: it handles off-calendar fiscal years correctly, sorts results by a primary metric, returns paired data with citation URIs, and sources data from SEC EDGAR/XBRL, FAERS, and FDA. This goes far beyond the annotations and informs the agent about side effects (none) and output structure.

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 trigger phrases, then methodically covers purpose, preference rule, data specifics, sorting behavior, output, and efficiency gains. Every sentence adds value; no filler. It is appropriately sized for a tool with two modes and complex data sourcing.

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?

This tool has no output schema, yet the description covers return values (paired data + citation URIs) and sorting behavior. It also explains data provenance, fiscal-year handling, and usage scope (2–5 entities). Nothing critical is missing, making it fully self-contained for correct invocation.

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

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

While the schema describes both parameters, the description enriches them with concrete semantics: for type="company" it specifies the exact financial fields (revenue, net income, cash, long-term debt), and for type="drug" it lists FAERS counts, FDA approvals, and trial counts. It also clarifies that values accept tickers/CIKs or drug names, adding practical usage detail beyond the schema.

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

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

The description opens with concrete trigger phrases and a clear statement: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." It specifies distinct data sources for company vs drug types and what metrics are pulled, making the tool's purpose unmistakable and differentiating it from single-entity lookup tools.

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

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

The description explicitly states "ALWAYS PREFER over sequential single-pack lookups when comparing entities," providing a clear when-not-to-use directive. It lists common user queries ("X vs Y", "rank these companies") that signal when to invoke the tool, and explains that it replaces 8–15 sequential lookups, giving concrete usage context.

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

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

The description adds substantial behavioral context beyond the annotations: account/paid-tier requirements, return packet contents (verbatim evidence, confidence, source, gaps[], contradictions[]), the 'never invented' guarantee, hop fields, citation_uri resolvability, semantic excerpting, and expected latency. This richly informs the agent about side effects, prerequisites, and output shape. It does not contradict the readOnly/idempotent/openWorld 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 justifiably so for a complex tool. It is front-loaded with critical account requirements and alternative guidance, and every sentence adds meaningful detail. It is structured logically from account/eligibility to use cases, behavior, and output characteristics, with no redundant fluff.

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

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

For a tool with only 2 parameters, no output schema, and high behavioral complexity, the description covers all necessary contexts: prerequisites, use cases, exclusions, return format, error behavior (gaps), timing, and citation semantics. An agent could reasonably decide when and how to invoke this tool without additional information.

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 descriptions for both parameters (100% coverage), so the baseline is 3. The description adds valuable semantics by linking depth levels to plan requirements (thorough is paid) and explaining how standard/thorough affect gap recovery and contradictions, which goes slightly beyond the schema's enum descriptions.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with decomposition and parallel routing. It also explicitly distinguishes itself from open-web search and sibling tools like ask_pipeworx, making its 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 gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and provides clear alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and when to fall back to ask_pipeworx if not signed in.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context about the return format: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It does not disclose potential rate limits or edge cases, but the added detail goes beyond baseline.

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

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

The description is four sentences, front-loaded with the core purpose. The list of domains is lengthy but relevant, and every sentence contributes useful information without fluff. It could be slightly tightened but is not excessive.

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 return value and readiness. It covers the tool's role as a discovery mechanism, including the types of domains and the 'Call this FIRST' guidance. This is sufficient for an agent to select and invoke the tool 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 description coverage is 100%, with all parameters including 'query', 'q', 'task', 'limit', etc., having descriptions. The description does not add extra parameter-level meaning beyond the schema, but the schema itself is comprehensive, so a baseline of 3 is appropriate.

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

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

The description clearly states that the tool 'Find[s] tools by describing the data or task,' which is a specific verb + resource. It distinguishes itself from siblings by positioning as a meta-tool to discover other tools, especially with the directive 'Call this FIRST when you have many tools available.'

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

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

The description explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' It also implies when not to use by saying 'not just one answer,' giving clear contextual guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral traits: patents API 'sunset May 2025 — soft-fails until reactivated', fallback chain 'GDELT→GNews', and returns are capped ('up to 5' filings). These details significantly inform the agent's expectation of tool behavior.

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

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

The description is long but every clause adds functional value—examples, data sources, return fields, constraints, and fallbacks. The opening example phrases are somewhat redundant but serve as quick-pattern recognition. Overall well-structured with dense information.

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

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

Given there is no output schema, the description thoroughly documents return sections (cik, recent_filings, fundamentals with sort order, patents soft-fail, news fallback, LEI). It also covers input constraints and data source specifics, making it self-sufficient for an agent to invoke the tool 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% and the description reiterates the same parameter guidance (ticker or zero-padded CIK, names not supported). It adds no new information beyond examples already in the schema, 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 clearly states the tool builds a 'full cross-source profile of a US public company' with a concrete verb (profile/brief) and specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It distinguishes itself from siblings by explicitly recommending it over chaining single-pack lookups.

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

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

Provides explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also notes the alternative for name-only inputs: 'use resolve_entity first if you only have a name.' This clearly defines when and how to use the tool.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds the use case of 'clear sensitive data' but does not disclose additional behavioral traits beyond the annotations (e.g., error handling, permanence, or effects on related data).

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

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

The description is two sentences, front-loaded with the core action, and every clause provides value—including usage context and sibling pairing. No wasted words.

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

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

For a simple single-parameter delete tool with full schema coverage and strong annotations, the description is complete. It covers what the tool does, when to use it, and how it relates to other tools, without needing to explain return values.

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 the key parameter fully described as 'Memory key to delete.' The description mentions 'by key' but adds no extra semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' This clearly states the action and target, and naturally distinguishes it from sibling tools like remember (store) and recall (retrieve).

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 when to use the tool: when context is stale, the task is done, or to clear sensitive data. It also names complementary tools (remember, recall), giving clear alternative and pairing 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 annotations by detailing the operational flow: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output is 'a single text blob ready to drop at site-root/llms.txt,' which is useful behavioral context. No contradiction with the annotations.

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

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

The description is remarkably concise: two sentences plus a use-case list. It is front-loaded with the main action, and every sentence serves a purpose—explaining what, how, and when to use the tool without 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 simple schema (2 params, no output schema), the description is complete: it explains the tool's purpose, process, output format, and use cases. It covers the return value ('single text blob') adequately, so an agent can select and 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 description coverage is 100%, so the baseline is 3. The description mentions the URL concept ('for any URL') and output context, but it does not add new semantic details for the 'max_links' parameter 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 states a specific verb+resource: 'Generate a production-ready llms.txt file for any URL.' It also explains the process (fetch, extract, emit) and the output format, clearly distinguishing this tool from siblings like 'scan_competitor_ai_presence' by focusing on the standard llms.txt output.

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

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

The description lists explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This provides clear context for when to use the tool, though it does not mention when-not-to-use or alternative tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral value by disclosing what the response contains (fields, geometry type, record count, capabilities), which helps the agent anticipate the output. 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?

A single, front-loaded sentence that lists specific outputs without any fluff. Every word earns its place.

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

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

For a simple 1-parameter tool with no output schema, the description adequately covers the return values. It could mention potential pitfalls (e.g., invalid URLs) but that is not essential. Overall complete for its complexity.

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

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

Schema coverage is 100% (the url parameter is fully described). The description confirms the parameter is used as the target URL but adds no extra semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Get') on a specific resource (ArcGIS Feature/Map Service layer's schema) and enumerates the exact output contents. This distinguishes it from siblings like query_layer, which is likely for querying features rather than schema.

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

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

Usage is implied: use this when you need a layer's schema, fields, geometry type, record count, or capabilities. However, no explicit guidance about when not to use it or alternatives (e.g., query_layer) is provided, so it relies on the agent to infer from context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the return field list and scoping to the caller's active subscriptions, but doesn't disclose additional behavioral details like pagination or rate limits.

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

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

Two sentences, no fluff, information-dense. The core action is front-loaded, and every sentence earns its place by adding either purpose or usage 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?

For a simple read-only list tool with one optional parameter, rich annotations, and no output schema, the description covers purpose, return fields, and use case sufficiently. There is no significant missing 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?

The sole parameter include_inactive is fully documented in the schema (100% coverage), so the description need not add more. It doesn't repeat or add param details, but baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description uses a specific verb 'List' with a clear resource 'the caller's active subscriptions' and enumerates the returned fields (id, type, params, etc.), making it distinct from siblings like subscribe/unsubscribe.

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

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

It explicitly states when to use it: to review current monitoring before adding more subscriptions or to find an id to cancel, referencing the actions of subscribing and unsubscribing. While it doesn't name alternative tools directly, the context is clear enough.

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

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

Annotations only provide generic false hints, so the description carries the full burden and does so richly: it discloses rate limiting (5 per identifier per day), that it is free and doesn't count against quota, anonymous filing returns a claim_token, and team reads digests daily. 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 somewhat long but every sentence earns its place: purpose, scope, exclusion, mechanics, limits. It is front-loaded with the core action and structured logically, with no filler or redundant restating of the title or 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?

For a tool with 4 params, a nested context object, and no output schema, the description is complete. It covers invocation, return token behavior, rate limits, and scope boundaries. There are no notable gaps in understanding how or when to use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics for claim_token (how to pass it back later to read resolution status) and advises 'Describe the issue in terms of Pipeworx tools/packs,' but it doesn't elaborate on individual parameters beyond what the schema already states.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from sibling tools by scoping exclusively to Pipeworx feedback categories (bug, feature, data_gap, praise) and explicitly excludes tools from other MCP servers.

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

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

Provides explicit when-to-use guidance for each feedback type and a strong when-not-to-use exclusion: 'if the tool came from a different MCP server... file it with that server instead.' Also instructs not to paste end-user prompts and explains how to use claim_token to check resolution.

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/destructive annotations, the description adds meaningful context: data is self-aggregating from the CF analytics-engine, contains no PII, is just (pack, tool, count), and is cached 5min–1h depending on window. This helps set expectations about freshness and privacy.

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-organized and front-loaded with the core purpose, followed by a structured bullet list. It is slightly longer than strictly necessary, but each sentence contributes useful information.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers what it returns, why it is useful, caching behavior, and data privacy. The annotations handle safety traits, so there are 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 input schema already provides 100% coverage for the single 'window' parameter, including its enum and explanatory text. The description merely echoes the options and adds a note about caching variability, which does not materially expand parameter meaning beyond the schema.

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

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

The description clearly states the tool reports what other AI agents are calling on Pipeworx, returning top tools, packs, and call volume over a selectable window. It distinguishes itself from siblings like discover_tools by focusing on social proof and current agent behavior rather than generic discovery.

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

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

A 'Useful for' section lists three concrete scenarios, making it clear when to apply the tool. However, it does not explicitly reference alternatives or provide when-not-to-use guidance, 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?

The description goes far beyond the readOnly/idempotent annotations by exposing internal logic: threshold checks, placeholder filter rules, Jaccard similarity threshold, and the fill-check behavior against live CLOB depth. It discloses failure modes (returns null when >20% placeholders) and clarifies that a positive theoretical edge may not be realizable in the book, teaching the agent to avoid trading false signals.

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

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

The description is long but densely packed, using recognizable labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to break up complexity. It is front-loaded with the primary purpose and mode selection, and every section adds unique operational detail. The length is justified given the tool's complexity, so it earns a 4 rather than a 3.

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 absence of an output schema, the description compensates by explicitly outlining the response structure (opportunities[], partition_check, fill_check fields) and covering edge cases like thin legs and low-similarity pairs. Sibling tool names are addressed where relevant, and the tool's role in the broader ecosystem is clear.

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

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

Schema coverage is 100% and each parameter is richly described with examples. The description adds substantial meaning beyond the schema: explains what each mode does, the difference between event and topic, what slugs/URLs look like, and how each parameter changes the search scope and comparator. This fully compensates and exceeds the schema's baseline.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three operational modes (no args, event, topic) and explicitly differentiates itself from siblings like polymarket_fill_risk and polymarket_edges by focusing on arbitrage detection rather than fill risk or edge tracking.

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

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

Explicit when-to-use guidance is provided for every mode: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)...', and 'topic (for cross-event scanning)...'. It also names a direct alternative for custom sizing ('use polymarket_fill_risk') and warns when not to trade (realizable_edge_pp <= 0), giving clear exclusions.

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

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

Annotations already declare read-only/idempotent. Description adds extensive behavioral detail: response segmentation, per-opportunity fields (edge_pp_net, kelly_fraction_half, liquidity, spread_pp), 24h-move warning, fed_candidates exclusion, diagnostics funnel, and 1h KV caching. This exceeds annotation coverage and gives the agent deep insight into tool behavior.

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

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

The description is long but well-structured, front-loading the purpose and then detailing segments, knobs, and diagnostics. It is dense with useful information; every sentence earns its place, though it could be slightly more compact for quick consumption.

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

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

Given there is no output schema, the description thoroughly describes response structure: by_segment, fed_candidates/fed_note, _diagnostics with funnel counters and filter_skips. It also explains why segments may be empty and how knobs affect results, making it complete for an agent to invoke and interpret.

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

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

Input schema has 100% coverage with detailed descriptions. Description adds a dedicated tradeable-edge knobs section explaining min_liquidity/max_spread_pp/min_partition_leg_kelly semantics, and adds context for slippage_pp (Polymarket fees/depth). This goes beyond the schema, though the schema already does heavy lifting.

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

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

Description states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear use case: 'what should I bet on today'. It distinguishes from sibling tools by describing three unique response segments (model_driven, structural_arbitrage, concentrated_longshot) and the benefit of discovering opportunities 'without paging hundreds of markets'.

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

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

Provides clear usage context: built for opportunity discovery, with knobs to enforce tradeable edge and diagnostics to explain empty segments. It does not explicitly name sibling tools or state when not to use it, but the use case and filtering guidance are 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds critical behavioral details: the 60-day snapshot TTL, snapshots written only on cache-miss, gaps meaning no scan, decay computed from daily closes not intraday, and signed edge_pp_net. 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 well-structured into purpose, arguments, RESPONSE fields, and limits. Despite its length, every sentence provides essential information with no waste. Front-loaded with a clear purpose statement.

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

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

With no output schema, the description thoroughly documents the return structure: tracked[] with full time-series, first_seen, trend, and decay metrics; expired[] with lifespan_days; and snapshot_dates[] with gap semantics. It also covers limitations, making it highly complete for a complex tool.

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

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

The schema already provides full descriptions, defaults, and clamps for both parameters. The description reinforces these with terms like 'lookback' and 'snapshot family' and ties them to the tool's purpose, adding context but not new syntax details beyond what the schema offers.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots,' answering a specific question about edge age and decay. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series behavior rather than current edges, with a concrete example that clarifies the use case.

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 contextual guidance, explaining that a fresh wide edge and a 3-week-old wide edge represent different trades, which implies when to use this tool. However, it does not explicitly name alternatives or state when not to use it, so some inference is required.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description correctly focuses on additional behavioral nuances. It details ladder walking, return fields like top_of_book, vwap_fill_price, slippage_pp, and the critical risk that partial basket fills can create an unhedged directional position.

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

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

The description is long but tightly structured with SINGLE-MARKET, BASKET, and USE THIS sections. Every sentence carries distinct information—mode behavior, parameters, outputs, and risk context—so the length 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?

With no output schema, the description enumerates the key returned values for both modes, including edge-case indicators like thin_legs, forced_directional_risk, and cannot_fill. It also states the dollar threshold for when to pre-check, making it fully actionable.

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 coverage is 100%, the description adds substantial meaning beyond the schema. It explains side options per mode, size_usd as 'max spend on buys, target proceeds on sells' for single-market and as settlement notional for basket mode, and clarifies that market/event select the mode.

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,' giving a specific verb and resource. It explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as the pre-trade fill-risk check.

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

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

It explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' making the trigger condition unambiguous. It also delineates when to choose single-market vs basket mode via market/event slug and warns of partial-fill risks that would suggest using this tool before execution.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes much further by explaining the compatibility_warning conditions, temporal_alignment meaning, and skipped_cross_type/subtype counters. It transparently discloses that most pre-mapped topics return warnings, setting accurate 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 dense but well-structured with sections (definition, modes, response, safety fields, caveat), and each sentence adds information. It is longer than average but appropriate for the tool's complexity. No redundant fluff except perhaps the repeated caution about pre-mapped vs tradeable, so 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 no output schema, the description explains the response shape ('leg-by-leg prices', 'matched spread[].top_spreads_pp') and all safety fields. It also covers both invocation modes and edge-case behaviors, making it self-contained for an agent to decide and 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?

The input schema already documents all three parameters with descriptions (100% coverage), providing baseline. The description adds meaning by explaining what the topic shortcuts do ('auto-fetch the matching event') and that explicit ticker/slug parameters override the mapped side. This clarifies interaction between parameters beyond schema.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states the tool's specific verb (compute), resource (cross-venue spread), and scope (same resolving question). It also distinguishes itself from general arbitrage tools by emphasizing venue pairings and equivalence checks.

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

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

The description provides two explicit usage modes ('TWO MODES') with examples, and warns that 'pre-mapped ≠ tradeable,' giving clear context for when to use it. It does not explicitly name alternative tools, but the usage guidance is strong enough to warrant a 4.

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 safety. The description adds that it returns attribute rows and geometry, and implies offset-based pagination. This adds some behavioral context but doesn't go into details like rate limits or response format.

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, zero filler: first states purpose and source, second lists parameters, third gives a concrete usage tip. Every sentence earns its place and the most important information is front-loaded.

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

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

Given strong annotations and full schema coverage, the description is complete for a read-only query tool: it explains purpose, where to get the url, parameters, return type (rows/geometry), and a sampling strategy. It could mention error cases or output format, but the complexity doesn't demand more.

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 all parameters thoroughly. The description repeats key parameters (where, out_fields, order_by, limit, offset) without adding new semantics beyond the schema; it only adds the url source context and note about geometry, which doesn't change 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 uses a specific verb 'Query' and resource 'ArcGIS Feature Service / Map Service layer', and specifies the url comes from search_datasets. This clearly distinguishes it from siblings like search_datasets (searching for datasets) and layer_info (metadata), 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 explicitly ties usage to a preceding search_datasets step (url comes from there) and provides a practical sampling tip (where='1=1' + out_fields='*'). However, it doesn't mention when not to use this tool or alternatives like layer_info, so it stops short of full exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by explaining scoping: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual behavior of retrieving vs listing when key is omitted. This 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 two sentences, front-loaded with the core action, and every clause adds value. It covers purpose, usage, scoping, and related tools without 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?

The tool is simple (one optional parameter, no output schema), and the description covers both operational modes and the scope. While it doesn't detail return format, the lack of an output schema and the straightforward nature of the tool make this acceptable. It is complete enough 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?

Schema coverage is 100% (the key property is described as 'Memory key to retrieve (omit to list all keys)'). The description reinforces this by explicitly noting the omit-key behavior and providing an example in the schema's examples. It adds semantic context by explaining that the key refers to values saved via remember, making the parameter's purpose clearer.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' This specifies the exact verb and resource, and differentiates it from sibling tools like remember and forget by explicitly naming them.

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

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

The description gives explicit usage context: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also names related tools and their complementary roles: 'Pair with remember to save, 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?

The description discloses mark_read behavior and the alternative HTTP endpoint, but the annotation readOnlyHint=true directly contradicts the mark_read parameter, which mutates read state. This is a clear annotation contradiction, making the transparency score 1 despite the description being otherwise transparent.

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 clear purpose: primary action, return payload contents, and filtering/mark_read/alternative access. The description is front-loaded with the verb and object, contains no fluff, and every sentence earns its place.

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

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

Given no output schema, the description covers return content (source, citation_uri, raw payload), filtering, mark_read side effects, and provides an alternate HTTP endpoint. Minor gaps like response ordering or default limit are covered by the schema. Overall, it is sufficiently complete for a read-only feed retrieval tool, aside from the annotation contradiction.

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

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

Schema covers all 5 parameters with basic descriptions, so the baseline is 3. The description adds meaningful value by giving a concrete example for type ('sec_8k'), explaining mark_read's effect on subsequent calls, and clarifying the since parameter as an ISO timestamp.

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: 'Pull fired events from your subscription feed.' It clearly states that it returns recent alerts with source, citation_uri, and raw payload, distinguishing it from sibling tools that manage subscriptions or perform searches.

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

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

It explains when to use the tool (pulling fired events from the feed) and provides usage details like filtering by type/since, mark_read, and polling suitability. However, it doesn't explicitly contrast with alternatives, though the context implies this is the go-to for recent alerts from the subscription feed.

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 read-only/idempotent/non-destructive, but the description adds substantial behavioral traits: parallel fan-out to three sources, GDELT preferred over GNews with fallback on rate-limit/5xx, USPTO soft-fail due to PatentsView sunset, and the shape of the return (changes[] grouped by source, total_changes, pipeworx citation URIs). No contradiction.

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

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

Front-loaded with query examples and functional summary, then details sources and return shape. Dense but every sentence carries useful info. Slightly long for a single paragraph, yet well organized; could be split for readability, but not wasteful.

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?

High complexity tool (3 sources, fallbacks, time-window parsing, citation URIs) with no output schema. Description covers input semantics, source behavior, fallback logic, and return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). Adequate for an agent to invoke and interpret results.

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

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

Schema coverage is 100%, but description enriches meaning: explains since accepts ISO date or relative shorthand with concrete examples ('7d', '30d', '3m', '1y'), clarifies value can be ticker or zero-padded CIK, and notes type currently only supports company. This goes beyond the schema's 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 concrete user intents ('What's new with X', 'latest on Y') and then states the core function: a change feed for a company over a time window. It clearly names the resources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from sibling entity_profile by contrast.

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 gives when to use (change feed for a company in last N days) and when not to use ('Use entity_profile instead when you want the static profile'). Also provides typical usage examples and explains fallback behavior across sources, which helps the agent 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?

Adds meaningful behavior beyond annotations: key-value scoping by identifier, persistence differences for authenticated vs anonymous users (24-hour retention), and pairing with recall/forget. 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?

Five short sentences, each earning its place: purpose, usage trigger, storage mechanics, persistence policy, and companion tools. Front-loaded with a clear first sentence and no fluff.

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

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

For a simple two-parameter tool, the description fully covers what the tool does, when to use it, how storage works, and retention nuances. No output schema is needed, and annotations cover safety aspects.

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 already provides 100% coverage with clear descriptions and examples for key and value. Description adds only the 'scoped by your identifier' context but does not deepen parameter semantics beyond what schema provides.

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

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

Description opens with a specific verb and resource: 'Save data the agent will need to reuse later', clearly indicating a memory store. It differentiates from siblings by referencing complementary tools (recall, forget) and providing concrete examples (ticker, address, preference).

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward...' and offers context on persistence. It names companion tools for retrieval/deletion, but does not explicitly state when not to use it or contrast with alternative memory-adjacent tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: it discloses graceful degradation of LEI/FIGI enrichment when external sources are unavailable, states that unresolved identifiers are explicitly listed under 'unresolved', and mentions internal cascading lookups. This goes beyond the structural hints.

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

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

The description is detailed and front-loaded with user phrasing examples, then states the purpose clearly. While long, each section adds necessary detail for entity types, resolution behavior, and enrichment. Slightly verbose but well-organized for the tool's complexity.

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

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

There is no output schema, so the description must explain likely outputs and behavior. It does so thoroughly: for company entities it lists returned identifiers (CIK, ticker, LEI, FIGI) with source labels, describes the unresolved field, and covers graceful degradation. For drugs it specifies RxCUI, ingredient, brand, and citation. This provides a complete picture of the tool's behavior.

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

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

Schema coverage is 100% and both parameters are described with examples and allowed values. The description provides examples (AAPL, 0000320193) and explains input formats, but these largely mirror the schema. Some added context about data sources and accepted inputs exists, but the schema already carries the core meaning.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers required by other tools. It provides specific verbs and resources (resolve, identifiers) and distinguishes from siblings like entity_profile by emphasizing its role as an ID lookup. The supported types are enumerated with data sources.

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

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

The description gives explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and outlines supported entity types with inputs and returns. It lacks explicit when-not-to-use or named alternatives, but the directive to use first implies differentiation from other tools.

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

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

Annotations already declare read-only, idempotent, and non-destructive. The description adds value by explaining that it probes each entity via ai_visibility_check, ranks results, and returns confidence and signal density. It also discloses that including 'anthropic' in models requires an _apiKey and makes external API calls, which is beyond the schema's plain field descriptions.

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 and well-structured: three sentences that front-load the purpose, then dive into process and use case. Every sentence adds information with no redundant fluff 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?

Although there is no output schema, the description specifies the return format (ranked list with score, confidence, signal density per entity). It also covers the default model behavior and optional key requirement, making the tool self-contained 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%, providing a baseline of 3. The description adds semantic value by stating that the first entity is treated as the 'subject' for narrative and the rest are competitors, and that context is shared across all probes. These details are not present in the schema definitions.

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

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

The description specifies exactly what the tool does: 'Compare AI visibility across multiple entities side-by-side' and details the process (probes each entity with ai_visibility_check, ranks by score). This clearly distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 an explicit use case ('competitive AI-marketing audits') with a concrete example, and notes that it internally uses ai_visibility_check, implying when to use this instead of calling the sibling directly. It does not give explicit exclusions, but the context is clear and actionable.

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

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

While annotations already mark the tool as read-only, open-world, idempotent, and non-destructive, the description adds substantial behavioral context: composite fan-out across two services, return shape (summary block fields, per-advisory detail, links, alternative versions), and degradation behavior. It discloses that bundlephobia's first measurement can take 5-30s and that sources_failed will list failures. This goes far beyond annotations and helps manage agent 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 dense but efficient, covering purpose, usage, return fields, ecosystem limitations, and timeout behavior in a single paragraph. The core purpose is front-loaded and every sentence earns its place. It is longer than the simplest examples but justified by the tool's composite nature.

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 compensates thoroughly by enumerating the summary block fields, per-advisory detail, links, and alternative versions. It also addresses failure modes (partial failures, sources_failed list) and ecosystem constraints. For a composite tool with no output schema, this provides a complete picture for an agent.

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

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

Schema coverage is 100% with both `package` and `version` already described in JSON Schema. The description does not add new meaning about parameters; it mentions "specific version" and "latest" but these are already in the schema. Baseline 3 is appropriate since the schema fully carries parameter documentation.

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: 'Composite "should I add this npm package to my project" check in ONE call', clearly stating it scans npm packages. It distinguishes from siblings by naming the fan-out across deps.dev and bundlephobia and the exact question it answers (safety, popularity, size). This is unambiguous and unique.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives an exclusion and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. This tells the agent both when to use this tool and when to use an alternative.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive, so the safety bar is met. The description adds valuable context by specifying the exact return fields (name, summary, record_count, owner/org, url) and mentions the open-world nature implicitly through 'search' and the examples. This adds useful 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 two sentences long, front-loaded with the main action and scope, and every word adds value. It efficiently communicates purpose, return values, and the connection to sibling tools without redundancy.

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

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

Despite no output schema, the description explicitly enumerates the return fields, making the tool's output predictable. It also provides context on how to use the result with sibling tools, making it self-sufficient for an AI agent to invoke and use 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?

The input schema already provides complete descriptions for all 3 parameters (query, limit, org_id), covering 100% of the schema. The description adds minimal parameter-level detail beyond saying 'by keyword', but since the schema is self-sufficient, 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 searches City of Pflugerville GIS open geospatial datasets by keyword, with specific examples of dataset types. It also distinguishes itself from siblings by explaining the returned url can be passed to query_layer / layer_info.

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

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

The description provides explicit guidance on when to use the tool (to find datasets by keyword) and what to do next (pass the url to query_layer / layer_info). This differentiates it from related sibling tools and gives a clear usage flow.

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 implementation details beyond the annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and a 200K char cap with truncation flagging. It also clarifies the return of character offsets and similarity scores, enriching the read-only/idempotent annotation 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 dense but well-organized: it opens with the core function, then adds use-case guidance, and finally gives technical details. No wasted words, though the final sentence could be split for readability. It is appropriately sized for the tool's complexity.

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

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

The description fully covers inputs, outputs, use cases, alternatives, and limitations. It specifies return content (passages, offsets, similarity scores), the 200K character cap and truncation behavior, and the relationship to ask_pipeworx_grounded. Despite no output schema, the description compensates 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 illustrative examples for the text parameter ('SEC 10-K body, an article, a long tool result') and query examples, but does not add meaning beyond what the schema already says about limit or defaults. It reinforces but does not significantly expand parameter semantics.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record,' with a specific verb and resource. It distinguishes from siblings by explicitly contrasting with ask_pipeworx_grounded and specifying the input is a previously fetched text, not a database-wide search.

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

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

The description provides explicit usage context: 'Use when the record is too big to cram into the prompt' and a direct pairing strategy with ask_pipeworx_grounded. It explains the workflow (fetch with gateway, then ground over passages) and the benefit (saves context, verifiable quotes).

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 numerous behavioral traits beyond the annotations: OAuth account requirement, inability for anonymous/BYO to persist, phone verification requirement, 10/day SMS cap, webhook signing secret returned only once, HMAC signature verification, and auto-disabling after 10 consecutive failures. It enriches the annotation-provided safety profile without contradiction.

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

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

The description is dense but appropriately sized for the tool's complexity. It front-loads the core purpose and then organizes supported types and delivery channels. However, it is a single block of text that could benefit from bulleted lists or clearer visual separation, slightly reducing 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 (3 params, nested objects, multiple subscription types, varied delivery channels), the description covers return value, auth requirements, type-specific params, delivery options, limits, and webhook details. With no output schema, it even explains the return value. This is complete for both selection and 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?

Although the schema covers 100% of parameters with descriptions, the description adds substantial semantic detail: per-type param examples (e.g., items:["5.02"] = officer change), delivery channel specifics (E.164 format, verified phone), webhook signing mechanics, and rate limits. This goes well beyond the baseline schema coverage.

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

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

The description states a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It clearly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on the creation of a subscription, and enumerates supported subscription types.

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 when to use the tool: to proactively monitor live-data streams via subscriptions. It also mentions the always-on feed alternative ('pull via recent_alerts or GET registry.pipeworx.io/alerts.json') and prerequisites (OAuth account). However, it does not explicitly contrast with sibling tools such as recent_alerts or list_subscriptions, so it lacks explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavioral context: it says the tool returns categories of examples, includes the exact tool and argument shape, and draws from a live catalog of thousands of tools. This goes beyond the annotations without contradicting them.

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

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

The description is a single, well-organized paragraph that front-loads example queries, then explains the return value, parameter usage, and when to use it. Every sentence provides distinct value, and there is no redundant information.

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

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

For a tool with one optional parameter and no output schema, this description is complete: it covers purpose, usage variants, parameter semantics, and output characteristics. It even names the meta-tools it helps learn, making it self-contained and sufficient for an agent to decide when and how to invoke it.

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

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

Although schema coverage is 100%, the description enriches the topic parameter by providing concrete examples ('finance', 'pharma', 'betting') and explaining the alternative of omitting it for a cross-category spread. This adds meaning beyond the schema's generic 'Optional focus area'.

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 ('returns') and defines the resource ('category-bucketed example questions with exact tool + argument shape'). It clearly distinguishes this from sibling tools by identifying it as 'the onboarding entry point' and recommending it 'FIRST' when unfamiliar with Pipeworx, unlike tools like ask_pipeworx or discover_tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also gives usage variations (no args vs. topic) and names alternatives (ask_pipeworx, entity_profile, compare_entities), making the guidance highly actionable.

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

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

Annotations declare this is not read-only and not destructive; the description adds important context: ownership is enforced, and the row is deactivated rather than deleted, preserving history via recent_alerts. This goes beyond the annotations and clarifies the exact 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 two sentences with zero waste: it covers purpose, ownership, and the non-destructive effect. Every clause 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 single-parameter cancel operation, the description is remarkably complete: it states the input, the constraint, the effect, and the after-effect. The lack of an output schema is mitigated by explaining the state change.

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

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

The schema already fully documents the 'id' parameter as a subscription uuid from subscribe, so baseline is 3. The description only repeats 'by id' without adding new semantics, so it does not push above baseline.

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

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

The description states 'Cancel a subscription by id', which is a specific verb+resource pair. It distinguishes from siblings like subscribe and list_subscriptions by clearly indicating it removes an existing subscription, and adds the deactivation nuance.

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

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

The description gives clear context: you use it to cancel your own subscription, with ownership enforcement stated. It doesn't explicitly contrast with alternatives like subscribe or list_subscriptions, but the purpose is unambiguous. No exclusions are given, so a 4 is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds important behavioral nuance: could_not_verify means the check did not happen and carries verification_error{stage,detail}, and unsupported means no source exists. It also discloses the automatic routing behavior and that the verdict list includes six possible outcomes. Minor gap: does not describe rate limits or latency, but with annotations covering safety, this is solid.

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 block with front-loaded examples and a clear structure: trigger phrases → when to use → routing → return verdicts → caller warning → replacement value. Each sentence earns its place, but it is somewhat long and could be broken into easier-to-scan sentences/lines.

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 pipelines, six verdicts, error semantics), the description covers the key behavioral contract well: verdict meanings, special handling for could_not_verify, and the structured vs grounded path. No output schema exists, so describing return verdicts is necessary and it does. It could mention example output or latency, but the core 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?

Schema coverage is 100%, so the schema already documents both parameters. The description adds context about tolerance_pct (hallucination detection use case, defaults) and claim wording, but does not go beyond the schema's parameter descriptions significantly. Baseline 3 is appropriate.

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

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

The description opens with natural-language query examples and states a specific verb+resource: 'natural-language claim verification against authoritative sources.' It also distinguishes from siblings by explicitly describing the dual pipeline (SEC EDGAR + XBRL for company-financial claims, grounded pipeline for all other claims).

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 'Use whenever the agent needs to check whether something a user said is factually correct,' and enumerates exact trigger phrases. It also gives when-not-to-interpret guidance: could_not_verify must not be shown as evidence. It contrasts with the alternative of 4-6 sequential calls, positioning this as a consolidation.

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