Arcgis Leecounty

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond those: the default model (Workers AI Llama-3.3-70b) is free, passing _apiKey incurs costs billed directly by Anthropic, and the return structure is per-model {score, confidence, signals, raw_response}. These are important operational traits 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 three sentences, front-loaded with the main purpose in the first sentence, followed by cost/default behavior and return format/use cases. Every sentence contributes necessary information 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?

There is no output schema, so the description rightly explains the return format ('per-model {score, confidence, signals, raw_response} + a combined view'). It also covers the primary use cases and the optional API key path. For a read-only probe with moderate complexity, this is sufficient and complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context beyond the schema by explaining that omitting 'models' defaults to workers-ai (free) and that passing _apiKey enables Anthropic probing at the user's cost. This clarifies parameter relationships and default behavior, pushing it above the baseline.

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

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

The description states a specific action ('Probe one or more LLMs') and a concrete outcome ('score visibility (0-100) per model'), clearly identifying the resource (business/brand/product/topic). This distinguishes it from sibling tools like ask_pipeworx or scan_competitor_ai_presence, which focus on asking questions or competitor-specific scanning.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context for when to use the tool. However, it does not mention when not to use it or name alternatives such as scan_competitor_ai_presence, so it lacks exclusions or fallback guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false; the description adds useful behavioral context beyond that: routing across sources, returning structured answers with stable citation URIs, being a fast default entry point, working on every tier, and implicitly distinguishing its less-grounded behavior from ask_pipeworx_grounded. No contradiction with annotations.

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

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

The description is long but appropriately dense: it front-loads the core routing directive, then uses trigger phrases, examples, and escalation paths. A few points are somewhat redundant ('PREFER OVER WEB SEARCH' followed later by 'even if web search could also answer it'), which prevents a perfect score, but the structure is organized and mostly every sentence earns its place.

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

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

For a router tool with 6 alias-only parameters, no output schema, and rich annotations, the description is complete: it explains what questions to send, what happens when the tool receives them, what the response looks like (structured answer plus stable citation URIs), and when to step up to siblings. Missing details like auth or rate limits are not necessary given the annotations and the tool's read-only, idempotent profile.

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

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

Schema coverage is 100% and the schema already documents aliases, so the baseline is 3. The description adds value by illustrating the expected natural-language form with concrete examples ('current US unemployment rate', 'Apple's latest 10-K', '5-day forecast for Tokyo') and clarifying that questions can be broad factual queries rather than tool-specific commands. This exceeds the baseline but doesn't need to do much more since the schema fully describes the parameters.

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

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

The description names a specific verb+resource: ask_pipeworx routes a question to one of 5,581 tools across 1,463 verified sources and returns a structured answer with pipeworx:// citation URIs. It also distinguishes itself from siblings by explicitly contrasting with ask_pipeworx_grounded and deep_research, so an agent can tell them apart without opening schemas.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and a trigger list ('what is', 'look up', 'find', 'get the latest'). It also provides escalation paths to ask_pipeworx_grounded for grounded single answers and deep_research for broad/multi-part questions, plus a note about breaking-news coverage through news feeds.

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/openWorld annotations, the description discloses that live routing candidates may be enabled during testing, that no candidate is active right now, and that the tool currently behaves identically to ask_pipeworx. It also clarifies that this is a full working router with no fallback, eliminating any concern that it is a stub. This is rich, honest behavioral context.

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

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

Every sentence earns its place: it states the beta identity, enumerates the sameness in scope, gives current candidate status, provides usage guidance, and addresses fallback concerns. It is information-dense without being repetitive, and the most important distinction 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?

Even without an output schema, the description tells the agent everything needed to invoke the tool correctly: what it is, how it relates to the stable version, when to use it, current behavioral state, and that it is fully operational. Referencing the same response shape as ask_pipeworx is sufficient given the stable sibling's existence.

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 the 'question' parameter and all five aliases with 100% coverage. The description adds no semantic detail about parameters beyond saying the tool takes the same arguments as ask_pipeworx. That is useful context but does not go beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies ask_pipeworx_beta as a universal router that routes natural-language questions across 5,581 tools, with the same arguments and response shape as ask_pipeworx. It explicitly distinguishes it from the stable variant and positions it as the experimental edge, leaving no ambiguity about what it does.

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

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

The description says to use it exactly like ask_pipeworx when you want the newest routing, which gives a clear selection condition. It references the stable router for comparison and mentions that no candidate is currently active, so the agent understands when beta behavior applies. It doesn't explicitly state 'use ask_pipeworx when you want stable behavior,' but this is strongly implied.

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

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

The description discloses several important behavioral traits beyond the annotations: it extracts only from the tool result, returns evidence with verbatim quotes, emits structured refusal reasons on failure, and costs one extra LLM call. These details meaningfully shape an agent's expectations about what the tool can and cannot do. No contradiction with the read-only annotations.

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

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

The description is dense but every sentence earns its place: purpose, routing, output format, refusal behavior, use cases, and cost tradeoff are all covered without filler. Important information is front-loaded with 'Hallucination-resistant answer mode' and then organized logically. The length is justified by the complexity of the decision between this and ask_pipeworx.

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 compensates fully by specifying the exact return shape and all refusal reasons. It also provides sufficient routing and usage context to allow correct selection and invocation. The complexity of a grounded-answer tool is fully addressed; nothing essential is missing.

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

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

Schema description coverage is 100%, so the input schema already fully documents the question parameter and its aliases. The description does not add parameter-level semantics, which is acceptable because the schema carries that burden. It does add context about how parameters get filled internally, but that is routing behavior rather than user-facing parameter detail.

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 a specific, named behavior: a hallucination-resistant answer mode that extracts answers only from tool results. It also explicitly differentiates from the sibling ask_pipeworx by describing the same routing but with grounded extraction and explicit refusals. This is a concrete verb+resource distinction, not a vague restatement.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and gives examples like financial verdicts and legal claims. It also explicitly tells the agent to prefer ask_pipeworx for casual lookups, naming the alternative and the cost tradeoff. This gives the agent a clear decision rule.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds extensive behavioral context: resolver match confidence and alternatives, low-confidence short-circuiting, closed-market status, illiquid-spread flag, cancellation-rule parsing and potential EV loss, and news fallback behavior on 429s. These go well beyond the annotations and inform safe usage.

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 highly detailed but quite long, composed of dense paragraphs with all-caps section headers. While every sentence carries useful information for such a complex tool, the sheer volume and wall-of-text style reduce scannability. It is not concise, but it is well-organized enough to be navigable for an agent that can process long text.

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

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

Given no output schema, the description thoroughly covers response shapes (result.market, result.analysis, result.evidence), the resolver contract (market_match_confidence, alternatives), parent_event extraction, news fallback fields, and various safety statuses. It even includes resolution-rule risk warnings. This is exceptionally complete for a tool of this complexity.

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

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

The input schema covers 100% of the three parameters with descriptions for each (market, depth, include_raw), including defaults. The tool description adds some examples of market inputs and mentions depth options, but it does not significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a clear, specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further explains the input formats (slug, URL, question text), lists use cases ('should I bet on X', etc.), and provides concrete examples. This clearly distinguishes it from broader tools like deep_research or other Polymarket-specific siblings.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear context for when to invoke the tool. It does not explicitly name alternatives or when not to use it, but the specific use-case guidance is strong enough to guide selection among siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: data sources (SEC EDGAR/XBRL, FAERS), fiscal-year handling, sort order, and citation URIs. No contradictions.

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

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

Despite length, every sentence earns its place: triggers, usage rule, data source details, sort behavior, and output format. Front-loaded with the core purpose and key preference rule.

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

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

Given no output schema, the description compensates by detailing return structure (paired data, citation URIs, sorted results). It covers both entity types and edges cases like off-calendar fiscal years, making the tool fully understandable.

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

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

Schema coverage is 100%, but the description enhances parameter understanding with concrete examples (AAPL, MSFT, ozempic, mounjaro), clarifies ticker/CIK vs drug names, and explains how the type parameter changes the data pulled.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one parallel call, with specific trigger phrases. It distinguishes itself from sequential lookups and sibling tools like entity_profile.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also gives trigger examples and distinguishes between company and drug use cases.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It reveals that research is grounded (not open-web search), that it always returns verbatim evidence, exposes gaps explicitly, never invents findings, and requires authentication with a paid tier for deeper depth. It could also mention rate limits or typical response times, but it covers the key behavioral implications for agent decision-making.

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 each clause adds value: auth constraints, alternative tool suggestion, method, output details, gap handling, and usage examples. It front-loads the critical account requirement. Slightly dense but well-structured, with the key caveats (account, use alternative) placed early.

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 both annotations and an output schema in the input, the description must self-contained. It covers inputs, outputs (findings with citations), scope (structured sources vs live news), auth, cost, and fallback behavior. This is nearly complete for an agent to decide and use 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?

Though the schema isn't provided here, the description clarifies the depth parameter's two values and their differing behaviors (standard gap recovery vs thorough lead-chasing), and implies the question parameter. This goes beyond just naming parameters and adds decision-relevant 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?

Description clearly states the tool performs grounded multi-source research over Pipeworx's structured data sources, with a specific verb (

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 and when-not-to-use guidance: sign-in required, paid plan for 'thorough' depth, fallback to ask_pipeworx if not signed in, use ask_pipeworx for single lookups and for breaking/current news topics. This leaves no ambiguity about when to call this tool vs alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing the return format ('top-N most relevant tools with names, descriptions, and full input schemas'), that results are 'ready to call directly', and that no second schema lookup is needed. This goes beyond the structured 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 front-loaded with the main purpose, then provides a useful domain list, followed by return value details and usage guidance. Every sentence contributes information, though the domain list is somewhat long. Overall it is well-structured and 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?

Despite lacking an output schema, the description explains what the tool returns (top-N tools with schemas and examples) and that results are directly callable. It also covers the broad scope and a usage pattern ('Call this FIRST'). Some details like ranking criteria or rate limits are absent, but the existing annotations and schema cover safety and parameters sufficiently.

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 reinforces the main parameter by saying 'describing the data or task', and the schema already documents aliases and the limit parameter with examples. The description doesn't add additional parameter semantics beyond the schema.

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

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

The description opens with 'Find tools by describing the data or task', which clearly states the tool's verb and resource. It also enumerates specific domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling tools by being the meta-search/discovery tool.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and adds 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'. This provides clear when-to-use context and implies when not to use (when a single answer is needed).

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 well beyond the annotations by detailing internal fan-out behavior across SEC EDGAR, XBRL, USPTO, news, and GLEIF, and discloses the patents API sunset and soft-fail behavior. It also lists specific return fields, making the tool's behavior highly transparent without contradicting the read-only/idempotent 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 dense but not wasteful; every clause adds valuable context. It is somewhat long and uses run-on sentence structure with semicolons, but the front-loaded examples and explicit guidance make it easy to scan and act on.

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 fans out across multiple sources, the description provides a clear mental model of inputs, outputs, fallbacks, and limitations. Even without an output schema, it enumerates the main returned fields and notes the soft-fail for patents, making it complete enough for an agent to decide 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 coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema: it explains accepted ticker/CIK formats, states that names are unsupported, and directs to resolve_entity as a prerequisite for name inputs. This enhances parameter understanding.

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

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

The description clearly states the tool's purpose: producing a full cross-source profile of a US public company in a single parallel call, with specific example queries. It distinguishes itself from sibling tools by explicitly preferring it over chaining single-pack SEC/XBRL/news lookups for holistic requests.

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 when the user asks for a holistic view or profile, prefer over chaining other lookups, and pass a ticker or CIK. It also gives an important exclusion/alternative: names are not supported, so resolve_entity should be used first if only a name is available.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, and the description simply restates the delete action without adding new behavioral nuance (e.g., irreversibility, side effects, error behavior). The mention of 'sensitive data' adds context but is more about purpose than operation.

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

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

Two sentences with zero waste. The first sentence states the action, the second provides usage conditions and relationships. Every word adds value and the description is front-loaded with the core purpose.

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

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

For a simple one-parameter tool with strong annotations (destructive, idempotent), the description covers what, when, and related tools. No output schema is needed, and the context signals are fully addressed.

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 described as 'Memory key to delete'. The description adds 'by key' but no additional detail about format, examples, or behavior. This meets the baseline but adds no extra 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 uses the specific verb 'delete' and the resource 'memory', with the method 'by key', making the tool's function immediately clear. It also distinguishes itself from siblings by mentioning 'remember' and 'recall', positioning this as the complementary deletion tool.

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

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

It explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also provides guidance on how the tool relates to others ('Pair with remember and recall'), effectively steering the agent toward appropriate usage.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds valuable process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and describes the output as 'a single text blob ready to drop at site-root/llms.txt'. This goes beyond annotations by explaining the internal steps and return 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 front-load the core function, then process, then use cases. Every sentence adds value with no fluff or repetition. The description is compact yet informative.

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

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

Given the tool's simplicity, the combination of schema, annotations, and description covers all necessary context. The description explains the output format since no output schema exists, and the annotations handle safety and idempotency. No significant gaps remain.

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

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

The input schema provides full coverage for both parameters (url and max_links) with descriptions. The tool description doesn't add additional parameter-level detail, but the schema already conveys the necessary semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL'. It specifies the resource (llms.txt), the action (generate), and the scope (any URL). It also distinguishes itself from siblings by focusing on the output artifact rather than analysis or monitoring.

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

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

Provides explicit use cases: '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 gives clear context for when to use the tool, though it doesn't mention exclusions 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 readOnlyHint and idempotentHint, so the safety profile is clear. The description adds useful context about the return contents (fields, geometry type, record count, capabilities) without contradicting annotations. No additional behavioral traits like rate limits or pagination are mentioned, but they are not necessary for this read-only operation.

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

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

A single, front-loaded sentence that conveys all essential information without redundancy. The verb and resource are stated first, and every word contributes to clarity.

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

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

For a simple read-only tool with one parameter, strong annotations, and no output schema, the description adequately explains what the tool returns and why it would be used. It is complete enough for an agent to 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 coverage is 100% for the single 'url' parameter, which already has a clear description. The tool description merely restates 'by url' without adding new format or syntax details, so it does not meaningfully compensate 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 uses a specific verb 'Get' and identifies the resource as 'an ArcGIS Feature/Map Service layer's schema by url', listing exact outputs (fields, geometry type, total record count, capabilities). This clearly distinguishes it from siblings like 'query_layer' which would query data rather than metadata.

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?

There is no explicit guidance on when to use this tool versus alternatives. The purpose is specific enough to imply usage (when schema is needed), but no alternatives or exclusions are mentioned, leaving the agent to infer use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by disclosing the exact return fields (id, type, params, etc.) and clarifying that only the caller's subscriptions are returned, which is behavior not captured 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?

Two sentences, each earning its place. The first clearly states the tool's action and return format, the second gives practical usage guidance. No redundant or filler content.

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

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

For a simple list operation with robust annotations and one documented optional parameter, the description is sufficiently complete. It states the return shape explicitly and offers usage context, covering all necessary aspects without the need for an output schema.

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

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

The schema fully documents the single optional parameter `include_inactive` with a clear description and default. The tool description does not add additional semantic detail about the parameter beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the action ('List') and the resource ('the caller's active subscriptions'), and specifies the return fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing rather than mutating.

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 concrete usage contexts: reviewing current monitoring before adding more subscriptions and finding an id to cancel. It implies when to use this tool relative to subscribe/unsubscribe, though it doesn't explicitly name alternative tools or state when not to use it.

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

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

Annotations are all false (readOnlyHint, etc.) and offer little insight. The description compensates fully: rate-limited to 5/day, free/no quota, claim_token flow for follow-up, daily digests, and roadmap impact. 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?

Though longer than average, each sentence serves a purpose: purpose, use cases, exclusions, input framing, token mechanics, rate limit, and cost. It is front-loaded with the core statement and organized logically with no 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?

No output schema exists, but the description explains the return value (claim_token), how to use it for follow-up, and covers rate limits, cost, and scope. This makes the tool's behavior fully predictable, even missing an output schema.

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

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

Schema coverage is 100% with detailed property descriptions, so baseline is 3. The description adds value beyond the schema by explaining the claim_token round-trip (pass back later to read status) and the guidance to frame message/context in Pipeworx terms, which is not in the schema.

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

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

Description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from the many research/search siblings and scopes it to Pipeworx connection tools only.

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 (bug, feature/data_gap, praise) and when not to (tools from other MCP servers), even naming the alternative (file with that server). Also instructs to describe issues in terms of Pipeworx tools/packs, covering both context and exclusion.

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?

Despite strong annotations (readOnly, openWorld, idempotent), the description adds valuable behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This goes beyond the annotations and informs the agent about data freshness and privacy characteristics.

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 front-loaded. It starts with the core functionality in the first sentence, follows with a bulleted list of use cases, and ends with key behavioral traits. Every sentence adds value, and the structure is scannable.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains the output format (pack, tool, count), the data source, and caching behavior. There is no missing context that would leave the agent uncertain about when or 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?

The schema description already fully covers the 'window' parameter with its enum values and the trade-off between short and long windows. The description repeats the values without adding new meaning. With 100% schema coverage, a baseline of 3 is appropriate; the description adds no additional 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 what the tool does: it returns top tools, top packs, and total call volume over a recent window. It also distinguishes itself from siblings by emphasizing 'what other AI agents are calling on' and gives concrete use cases (e.g., confirming a canonical choice before asking a question) that separate it from 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?

The description provides three explicit use cases: discovering hot data sources, confirming a popular tool as canonical, and checking alignment with agent needs. It also gives guidance on window selection (shorter windows for current trends, longer for steady-state). It does not explicitly name alternatives or say when not to use it, but the context is clear enough for an agent to decide.

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

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

Annotations already provide readOnly/openWorld/idempotent hints, but the description adds substantial behavioral detail: the Jaccard similarity threshold for cross-event pairing, placeholder filtering rules, partition-check logic, and the fill-check pricing against live CLOB depth. This goes far beyond the annotation safety profile and discloses internal logic, thresholds, and output semantics.

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

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

The description is long but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every sentence carries needed information, though the density makes it less concise than ideal for a quick scan. Slight over-explanation occurs, but the organized format keeps it navigable.

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

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

With no output schema, the description fully explains the response structure (opportunities[], partition_check fields) and critical edge cases (placeholder filters, similarity threshold, realizable edge <= 0). It also covers all three modes and directs to a sibling for custom sizing, making the tool self-sufficient even for complex arbitrage scenarios.

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

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

Although the schema already documents both parameters, the description adds concrete examples (event slugs like 'fed-decision-may-2026', topic seeds like 'Strait of Hormuz traffic returns to normal'), explains mode-specific behavior (partition_check vs cross-event comparator), and clarifies recommended usage. This is valuable beyond the schema's parameter descriptions, enriching the agent's understanding of each argument.

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 opening sentence clearly states a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It differentiates from siblings like polymarket_edges and polymarket_edge_tracker by focusing on structural arbitrage checks and explicitly describing three modes (trending, event, topic), 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 mode selection criteria: call with no args for a trending scan, pass event for a specific market, pass topic for cross-event scanning. It also points to polymarket_fill_risk for custom sizing and explains when NOT to trade (realizable_edge_pp <= 0), providing clear when-to-use and when-not-to-use guidance.

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

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

The description adds numerous behavioral details beyond the readOnlyHint/openWorldHint annotations: it discloses caching ('Cached 1h at the KV level keyed on all knobs'), explains the response structure including _diagnostics for empty segments, and describes subtle behaviors like 'Partition arbs always return kelly_fraction_half=0 at the parent level by design.' It also warns about the 24h-move scenario, giving agents a clear picture of the tool's runtime behavior. No contradictions with annotations.

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

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

The description is a dense, single-paragraph wall of text with many embedded asides and clauses. While every sentence carries useful information, the lack of sections or bullet points makes it hard to scan, and it is significantly longer than necessary. It is thorough but not concise; it would benefit from structuring the segment explanations and knob descriptions separately.

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 present, the description fully covers the response contract: by_segment{...}, fed_candidates/fed_note, and _diagnostics. It also details the metrics carried by each opportunity (edge_pp_net, kelly_fraction, liquidity, spread_pp, volume) and the purpose of each knob. For a complex tool with 9 parameters and no output schema, this is remarkably complete.

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

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

Even though the schema already documents all 9 parameters, the description adds crucial interaction semantics. For instance, it explains that min_liquidity / max_spread_pp 'drop opportunities where edge isn't realizable' and that min_partition_leg_kelly filters partitions by per-leg Kelly because 'min_kelly never filters them.' This goes beyond the schema's parameter definitions and helps agents choose knobs correctly.

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

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

The description opens with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' clearly stating the verb, resource, and purpose. It also distinguishes the tool from siblings by noting it exists for 'what should I bet on today' and avoids 'paging hundreds of markets,' which sets it apart from tools like polymarket_arbitrage or polymarket_edge_tracker.

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 frames the tool's use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides limitations, such as the unreliability of Fed bets without paid OIS/SOFR-futures data, and notes that concentrated_longshot opportunities are 'rare-by-design.' However, it does not explicitly name alternative tools or state when not to use this tool, 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 annotations only state read-only, open-world, idempotent, and non-destructive hints. The description goes far beyond these by disclosing specific limitations: 60-day snapshot TTL, snapshots only written on cache-miss, data gaps, and decay computed from daily closes net of slippage. This is rich behavioral context that significantly aids an agent in interpreting results.

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

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

The description is longer than a typical two-sentence one, but it is well-structured with labeled sections for Args, RESPONSE, and LIMITS. Every section delivers essential information about output shape and caveats without redundancy, making the length justified.

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 return values. It thoroughly details tracked[], expired[], and snapshot_dates[], including computed fields like decay_pp_per_day and lifespan_days, and covers TTL limits. This makes the tool self-contained and easy 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% and both parameters already have descriptions including defaults and clamps. The description repeats defaults ('days' default 14, max 30; 'window' default 1wk) and uses the phrase 'snapshot family,' but this adds no new meaning beyond the schema. The baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It then directly answers the core question the tool addresses, distinguishing it from sibling tools like polymarket_edges by focusing on the persistence/decay of edges rather than their computation.

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

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

The description provides clear usage context by contrasting a fresh wide edge with a 3-week-old one, implying this tool is for checking edge history before trading. It does not explicitly name alternatives or exclusion criteria, but the practical guidance is evident.

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?

Despite annotations already declaring readOnlyHint=true, openWorldHint=true, and idempotentHint=true, the description adds rich behavioral context: it walks the order-book ladder, returns specific diagnostics (slippage, shares_filled, verdict), and explicitly warns about the risk of partial basket fills leading to unhedged directional positions. It also explains the interpretation of size_usd differently across modes. This goes well 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 long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence carries meaningful information about modes, parameters, outputs, or risk. While dense, it is appropriately sized for a tool with two operational modes and no output schema, making it a 4 rather than a 5.

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

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

With no output schema, the description carries the full burden of explaining return values. It enumerates all key outputs: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, and forced_directional_risk. It also covers mode selection, required parameters, and risk implications, making it highly 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 covers all four parameters with 100% description coverage, so the baseline is 3. The tool description adds value by explaining mode-specific semantics: size_usd is 'max spend on buys, target proceeds on sells' in single-market mode vs 'settlement notional S (shares per leg; each share pays $1)' in basket mode. It also clarifies side defaults (auto-detection for basket). This enhances the schema's descriptions, earning a 4.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket), enumerates output fields, and differentiates itself from sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade.' This is a clear, specific purpose with sibling differentiation.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books not capturable, partial basket fills convert arb into unhedged directional position). This is explicit usage context with clear alternatives implied (use before arbitrage/edge 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 only provide readOnly/openWorld/idempotent hints, leaving the description to carry the burden of behavioral disclosure. It richly explains safety fields: compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. It discloses edge cases (matched_pairs:0) and clarifies when spreads are mathematically meaningless, going far beyond the structured annotations.

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

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

The description is lengthy but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds important information; the caveat at the end is critical for correct usage. It could be slightly tightened, but the density warrants its length.

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

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

With no output schema, the description must explain return values, and it does: per-venue leg prices, matched spread[], top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. It also covers failure modes and interpretation, making the tool fully understandable 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% (each param has a description), which sets a baseline of 3. The description adds value by framing the two modes and how override works ('explicit kalshi_event_ticker + polymarket_event_slug for custom pairings'), plus giving concrete examples ('fed', 'btc') within the schema. It clarifies the relationship between params without just repeating schema text.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly states the tool's function, distinguishes it from same-venue arbitrage tools (via the 2-25pp delta and bet-shape equivalence concept), and explains what it does not do (fabricate spreads when outcomes aren't equivalent).

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 describes two usage modes (topic shortcuts vs explicit ticker/slug) and gives strong contextual guidance: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests... pre-mapped ≠ tradeable.' However, it does not explicitly name sibling alternatives (e.g., when to use polymarket_arbitrage instead), so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds behavioral context by noting the return of attribute rows and geometry, the SQL-like nature of where, and a sampling pattern. It doesn't go into pagination details, but schema covers offset and limit.

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

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

Two sentences, front-loaded with the main action, no fluff. The description efficiently conveys purpose, key parameters, and a usage tip in minimal space.

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 query tool with a rich schema and clear annotations, the description covers the essential aspects: what it queries, how to construct queries, and what to expect in return. It omits advanced error handling or edge cases, but those are not necessary for a well-scoped 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% and all parameters have descriptions, so the description adds limited additional meaning. It does mention 'SQL-like where' and the sampling pattern, which provides some context beyond schema, but the schema already explains each parameter adequately. 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 states a specific verb ('Query') and resource ('an ArcGIS Feature Service / Map Service layer'), and distinguishes itself from siblings by referencing search_datasets as the source of URLs and listing query-specific parameters (where, out_fields, order_by, limit, offset). This clearly separates it from metadata tools like layer_info.

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

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

The description implies a workflow ('by its url (from search_datasets)') and provides a concrete usage tip for sampling all data (where="1=1" + out_fields="*"). It doesn't explicitly exclude alternatives like layer_info or search_within, but the context is clear enough for a query tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing scoping to a specific identifier (anonymous IP, BYO key hash, or account ID) and the complementary relationship with remember/forget. However, it does not describe behavior for missing keys or the exact return 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?

The description is compact and front-loaded: first sentence states the action, second gives rationale and examples, third adds scoping and sibling pairing. Every sentence earns its place with no redundant or vague wording.

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, good annotations, and no output schema, the description adequately covers retrieval, listing, scoping, and sibling relationships. However, because there is no output schema, it could be more explicit about the return format (e.g., what a missing key returns) to reach full completeness.

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 documents the single 'key' parameter with 100% coverage, including the omit-to-list behavior. The description echoes this ('omit the key argument') and adds example use cases (ticker, address, notes), but adds no significant semantic details 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 uses a specific verb ('Retrieve') with a clear resource ('a value previously saved via remember') and also covers the list-all-keys mode. It explicitly distinguishes itself from sibling tools 'remember' and 'forget' by positioning itself as the complementary lookup operation.

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

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

It states exactly when to use this tool: 'Use to look up context the agent stored earlier' with concrete examples (target ticker, address, research notes). It also mentions scoping to an identifier and pairs with 'remember' and 'forget', providing clear usage context without needing an explicit exclusion clause.

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 explicitly states that setting mark_read:true flags events as read and 'the next call only shows newer ones,' which is a persistent state mutation. This directly contradicts the annotations readOnlyHint=true and idempotentHint=true, triggering the annotation contradiction rule.

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

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

Four sentences, front-loaded with the core purpose. Every sentence adds value: return payload, filtering options, mark_read side-effect, polling suitability, and the alternate registry endpoint. No filler or redundancy.

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

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

Despite no output schema, the description adequately covers the return payload and core behaviors. The schema covers limit and unread_only. The mark_read side-effect is disclosed, but the contradiction with readOnlyHint makes the overall contextual story inconsistent, preventing 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, but the description adds practical meaning beyond the schema: an example type value ('sec_8k'), clarification that since is an ISO timestamp, and the behavioral consequence of mark_read on subsequent calls. This goes beyond the raw schema descriptions.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It clearly identifies the return payload (source, citation_uri, raw event payload) and differentiates itself from sibling tools like recent_changes by focusing on the evaluator's persisted subscription feed.

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: filtering by type and since, mark_read behavior, and that polling works fine. It also names an alternative HTTP endpoint for scripts/dashboards. It does not explicitly contrast with sibling MCP tools, but the usage scenarios are 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?

Discloses data sources (SEC EDGAR, GDELT→GNews fallback, USPTO) and the PatentsView sunset soft-fail behavior. Describes the return structure including grouped changes, total count, and citation URIs, going well beyond the annotations.

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

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

The description is appropriately sized and front-loaded, beginning with user intents, then mechanism, parameters, return, and alternative. Every sentence adds value, and the flow is logical without unnecessary verbosity.

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

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

Even without an output schema, the description fully covers the return format and content. It also explains source fallback behavior and provides an alternative tool, making it complete for an agent to select and invoke confidently.

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?

Explains `since` formats (ISO date or relative shorthand) with concrete examples and even recommends '30d' or '1m' for typical monitoring. Clarifies that `value` can be a ticker or zero-padded CIK, adding practical guidance 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 this tool provides a time-bounded change feed for a company, with user-intent examples. It distinguishes itself from entity_profile by explicitly contrasting change feed vs static profile.

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

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

It explicitly says to use entity_profile instead when a static profile is desired, providing a clear when-not. The description also establishes the intended query patterns and notes the efficiency of a single parallel call.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds important context: memory is 'scoped by your identifier' and 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' These details are not in 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?

Three sentences with clear front-loading: first sentence states the action, second gives when-to-use, third covers storage/persistence and related tools. No filler 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 2-param write tool with no output schema, the description covers everything needed: purpose, usage, persistence/auth behavior, and relationships to recall/forget. Nothing essential is missing.

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

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

Input schema already covers 100% of parameters with detailed descriptions and examples. The description adds meaning by explaining the key-value pair is 'scoped by your identifier' and by providing concrete domain examples (ticker, address, preference, research subject), which enriches the schema's generic 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?

Description opens with 'Save data the agent will need to reuse later' — a specific verb and resource. It clearly distinguishes from sibling tools by explicitly pairing with 'recall' and 'forget'.

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

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

States 'Use when you discover something worth carrying forward' and frames the tool as a way to avoid re-looking-up information. The closing sentence instructs pairing with 'recall to retrieve later, forget to delete', giving explicit alternative guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value beyond these by detailing internal cascading lookups, graceful degradation of LEI/FIGI enrichment, and explicit handling of unresolved identifiers. No contradictions with annotations.

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

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

The description is front-loaded with example queries, which is effective. It is somewhat verbose with multiple sentences and bullet-point-like details, but every sentence adds useful information. Could be slightly more concise, but the structure is logical and easy to scan.

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

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

Given the tool's complexity, no output schema, and two parameters, the description is remarkably complete. It covers supported types, input variations, resolution behavior, output format (including unresolved identifiers), graceful degradation, and source attribution. The agent has all necessary context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description significantly enriches parameter meaning by providing concrete examples for each type, explaining value formats (e.g., ticker vs CIK vs ISIN), and describing resolution behavior per type. This adds substantial value beyond the schema's minimal 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 purpose: resolving a user-spoken name to canonical/official identifiers that other tools require as input. It provides concrete examples ('What's the ticker for...', 'find the CIK for...') and distinguishes the tool from siblings by explicitly noting it replaces 2-3 manual lookups, which is unique among the sibling list.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' This clearly tells the agent when to use the tool. However, it does not explicitly mention when NOT to use it (e.g., if IDs are already known) or reference alternative sibling tools. The guidance is strong but not exhaustive.

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

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

Annotations already signal read-only, idempotent, open-world behavior. The description adds that it probes each entity via ai_visibility_check, ranks results, and returns score, confidence, and signal density. This is meaningful behavioral detail beyond the annotations, though it omits API cost specifics which the schema covers.

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 dense with information. It starts with the core purpose, then explains behavior and return format, followed by a concrete use case. No unnecessary wording.

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

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

The description covers the use case, internal behavior, and return format, and the schema covers parameters and constraints. Without an output schema, the description's mention of 'ranked list with score, confidence, signal density' is sufficient context. It could mention limits (max 8 entities) but that is in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description's mention of 'your brand + N competitors' mirrors the schema's entities description and adds no new parameter semantics. 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's function: comparing AI visibility across multiple entities side-by-side. It distinguishes itself from sibling 'ai_visibility_check' by focusing on multi-entity comparison and ranking, and names the underlying probe.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and illustrates it with a question. It does not explicitly exclude alternatives, but the multi-entity comparison context and mention of N competitors imply when this beats single-entity checks.

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

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

Discloses multi-source fan-out, partial failure degradation, first-measurement delay, and the existence of sources_failed in results—all beyond the annotations. Annotations already indicate read-only/idempotent, and the description adds operational behavior 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?

Densely packed with high-value information: purpose, sources, use cases, return fields, ecosystem scope, and failure behavior. No filler or repeated schema content; 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?

No output schema exists, so the description compensates by enumerating the return fields, describing per-advisory details, links, and version alternatives, plus failure modes. For a complex composite tool, this is comprehensive and leaves little unknown.

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?

Both parameters are fully documented in the schema (100% coverage). The description adds no additional parameter-specific meaning beyond what the schema already provides, so the 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 opens with a specific purpose ('should I add this npm package to my project' check in ONE call) and names the exact data sources (deps.dev and bundlephobia), clearly differentiating it from generic dependency tools. It also lists what it returns, making the tool's role unambiguous.

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

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

Explicitly states when to use ('Use whenever an agent asks...') and provides an exclusion for other ecosystems ('PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), directing to an alternative path. This is strong guidance for tool selection.

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

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

With annotations already covering read-only, open-world, and idempotent behavior, the description adds value by disclosing what the tool returns (name, summary, record_count, owner/org, url) and how results should be used (pass url to query_layer/layer_info). This is sufficient behavioral transparency given the strong annotation support and no contradictions.

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

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

The description is two sentences, front-loaded with the main purpose and immediately followed by return-value details and downstream usage. Every sentence earns its place, with no filler or redundancy. It is efficient and well-structured.

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

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

Given the tool's moderate complexity, 3 parameters, and the absence of an output schema, the description adequately covers what the tool does, what it returns, and how to use the result. It names the domain (Lee County GIS) and lists the return fields, which is sufficient for an agent to invoke the tool and interpret the response. No critical gaps.

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

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

The input schema already describes all three parameters (query, limit, org_id) with 100% coverage, so the description does not need to add much. It reinforces that search is by keyword and that org_id overrides the default Lee County GIS scope, but these details are already present in the schema. The description adds minimal new parameter meaning beyond what the schema provides.

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

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

The description clearly states the tool's function with a specific verb ('Search'), a defined resource ('Lee County GIS open geospatial datasets'), and a scoping mechanism ('by keyword'). It also distinguishes itself from sibling tools by explicitly mentioning that it returns a Feature Service url to pass to query_layer/layer_info, which clarifies its role as a discovery tool rather than a query tool.

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

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

The description provides context on when to use the tool: when you need to find datasets by keyword and then use the returned URL with query_layer or layer_info. However, it does not explicitly contrast with other search-related siblings like search_within, nor does it state when not to use it. The downstream workflow is clear, but exclusions are absent.

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

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

Beyond the readOnly/idempotent annotations, the description discloses concrete behavior: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and caps input at 200K chars with truncation flagging. 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 slightly long but front-loaded with the core purpose and every sentence carries distinct value: usage scenario, pairing, technical details, and constraints. It is well-structured but could be trimmed slightly without losing critical 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 without an output schema, the description explains return format (passages, offsets, scores), algorithm details, input constraints, and the intended workflow with ask_pipeworx_grounded. This is comprehensive 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?

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by giving meaningful query examples ("supply-chain risk") and explaining the text parameter's role as already-fetched content, plus reiterating the character cap. This justifies 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 states a specific verb and resource: "Semantic search INSIDE a fetched record." It distinguishes itself from siblings by explicitly scoping to already-pulled text (e.g., SEC 10-K body, article) and by contrasting with ask_pipeworx_grounded, making its unique role clear.

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

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

The description provides explicit usage guidance: "Use when the record is too big to cram into the prompt" and names the sibling tool ask_pipeworx_grounded as a pairing alternative. This offers clear when-to-use and alternative 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true), the description adds key behavioral details: returns a subscription id, requires an OAuth account, SMS delivery has a 10/day cap and phone verification, and webhook auto-disables after 10 consecutive failures. These are valuable operational traits not visible in annotations.

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

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

The description is a single dense paragraph, front-loaded with the primary purpose, and every sentence adds essential information. It efficiently packs account requirements, supported types with examples, and delivery channel options without waste.

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

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

The description covers the core workflow, return value, account prerequisites, and delivery options, but omits two supported types (patent_grant, clinical_trial) from its list, which could mislead an agent about the full enum. The schema compensates, but for a complex tool with nested objects and no output schema, the description could have been more exhaustive.

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

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

The schema already covers all parameters with 100% description coverage, including per-type params. The tool description adds semantic interpretation (e.g., items:["5.02"] = officer change) and examples, going slightly beyond the schema. However, it omits two enum types (patent_grant and clinical_trial) that the schema does cover, so it doesn't fully complement 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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription id. It distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on the creation action, and names specific supported 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 explicit when-not-to-use guidance by requiring a Pipeworx OAuth account and noting anonymous/BYO cannot persist subscriptions. It also mentions an alternative pull mechanism (recent_alerts or GET registry.pipeworx.io/alerts.json) for the always-on feed, giving clear context for when to use this tool vs pulling alerts directly.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, but the description adds substantial behavioral context: it explains the output structure (category-bucketed example questions with exact tool+argument shape), the source (live catalog of thousands of tools), and the mode switching (full spread vs. focused). No conflict with annotations.

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

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

The description is a single run-on sentence with many clauses, but every clause contributes useful information (query phrasings, categories, tool+arg shape, parameter guidance). It is dense but not wasteful; a bit more structuring would improve readability.

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

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

For a tool with no output schema, the description fully conveys what to expect: category-bucketed example questions with tool and argument shape, a list of categories, usage scenarios, and parameter guidance. Combined with strong annotations and full schema coverage, it is a complete onboarding description.

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

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

Schema coverage is 100% with the `topic` description already listing all focus areas and the omit behavior. The description adds a few examples ('finance', 'pharma', 'betting') but no additional semantic meaning beyond what the schema provides. 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 states the tool's purpose precisely: it is the 'onboarding entry point' that returns category-bucketed example questions with the exact tool and argument shape. It distinguishes itself from siblings by being the 'Use this FIRST' tool and mentions learning to call meta-tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and further clarifies when to call with no arguments vs. passing a `topic` to focus. It also points to meta-tools like ask_pipeworx, entity_profile, and compare_entities, providing clear alternatives.

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

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

The description goes beyond the annotations by disclosing that the row is deactivated, not deleted, and that historical events remain available via recent_alerts. It also reveals ownership enforcement, which is a significant behavioral constraint. These details align with the annotations (destructiveHint false, readOnlyHint false) and add substantive context that the structured annotations alone do not convey.

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

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

The description is two sentences long, with the primary purpose front-loaded in the first sentence and essential behavioral details in the second. Every clause adds value, and there is no redundancy or extraneous information. It is 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?

Despite having no output schema, the tool is simple (one parameter) and the description covers all critical aspects: purpose, ownership, deactivation semantics, and relation to recent_alerts for historical access. The annotations further provide idempotency and non-destructiveness info, so the combined context is complete for an agent to select and invoke the tool correctly.

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

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

The input schema fully documents the single parameter 'id' as 'Subscription id (uuid) returned by subscribe.' The description's mention of 'by id' reinforces this but adds no additional semantic detail. Since schema coverage is 100%, a baseline score of 3 is appropriate, and the description does not need to compensate for any gaps.

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 'Cancel a subscription by id,' which clearly specifies the action (cancel), the target (subscription), and the method (by id). It also distinguishes this tool from siblings like subscribe and list_subscriptions by explicitly stating the deactivation behavior and ownership enforcement, making its unique purpose unmistakable.

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

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

The description provides clear context for when to use this tool: it cancels a subscription by id, and ownership is enforced, meaning you can only cancel your own subscriptions. It also explains the consequence (deactivation, not deletion) and points to recent_alerts for historical events, giving a sense of the appropriate use case. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a perfect 5.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds critical behavioral context: the two distinct pipelines (SEC/XBRL fast path vs grounded pipeline) and essential semantic distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists), which is crucial for correct interpretation.

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 exceptionally well-structured: it front-loads the purpose with trigger phrases, then explains the two modes, return values, and important caller caveats. Every sentence earns its place, and the 'IMPORTANT' note is prominently placed.

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

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

No output schema exists, yet the description thoroughly explains the return verdicts, citation, reasoning, and error semantics. It also covers the different handling of financial vs other claims, making it sufficiently informative for the agent to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100% and both parameters already have detailed descriptions. The tool description does not add significant parameter-specific meaning; it only mentions 'exact percent-delta math' indirectly. 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's function as 'natural-language claim verification against authoritative sources' with specific trigger phrases, and differentiates from siblings like ask_pipeworx by focusing on verifying factual claims with verdicts rather than general Q&A.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' This gives clear context, but it does not mention when NOT to use it or name alternatives, stopping short of a full 5.

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