Arcgis Fairfax

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

The annotations already declare readOnly/idempotent/non-destructive behavior; the description adds valuable context about the free default model, the need for a BYO Anthropic key with direct costs, and the per-model return structure. This goes beyond the annotations without contradicting them.

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

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

Two efficient sentences pack the core purpose, configuration options, return structure, and use cases without any fluff. Information is front-loaded with the main action first.

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 adequately explains the returned data shape and configuration choices. It covers purpose, usage, and behavior, though it omits details like rate limits or error handling, making it slightly incomplete for a tool with 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?

Schema coverage is 100% and the schema already documents `models` and `_apiKey`, so the baseline is 3. The description adds some extra meaning by clarifying the cost implications of `_apiKey` and the default model selection, but does not substantially extend the schema's parameter descriptions.

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

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

The description uses a specific verb ('Probe') and clearly identifies the resource (LLMs' knowledge of a business/brand/product/topic) and the deliverable (visibility score 0-100 per model). It distinguishes the tool from siblings like ask_pipeworx by focusing on scoring brand visibility rather than general Q&A, though it does not explicitly name alternative 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 clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass `_apiKey` (to also probe Anthropic). It does not include explicit exclusions or comparisons to alternative tools, so it falls short of the 5-level guidance.

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

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

The description discloses key behaviors: routes to one of 5,581 tools, fills in arguments, returns structured answer with citation URIs, works on every tier. It does not mention rate limits, failure modes, or output format details, but no annotations are provided to lean on. Given the tool's complexity, this is solid behavioral disclosure, though it could mention limitations like not hallucinating or handling ambiguous queries.

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

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

The description is long but densely informative. It front-loads the primary usage ('PREFER OVER WEB SEARCH'), then lists domains, provides examples, and clarifies when to use alternatives. Every sentence adds value; it is not padded. However, it could be slightly trimmed without losing meaning, which prevents 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?

Given the tool's complexity (5,581 tools, many domains), the description covers the what, when, why, and how, including examples and alternatives. It explains the routing behavior and citation URIs. No critical information is missing for an agent to decide 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 input schema already documents the parameter well with aliases and descriptions. The tool description does not add much beyond what the schema provides, but it does imply the parameter is a natural language question. Since schema coverage is high (>80%), 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 routes questions to authoritative data sources with citations, and explicitly distinguishes it from siblings like ask_pipeworx_grounded and deep_research. It is specific about the resource (5,581 tools across 1463 verified sources) and the action (routes, fills arguments, returns structured answers with citation URIs).

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 this tool ('PREFER OVER WEB SEARCH', 'default entry point'), and when to step up ('for hallucination-resistant single answer use ask_pipeworx_grounded', 'for broad multi-source use deep_research'). Also covers news/live queries. This is textbook usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that the tool is a full working router (no fallback) and that its behavior may change when routing candidates are enabled, plus a specific last-active date. This goes beyond the structured hints and clarifies the experimental state 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 moderately long but each clause adds value: it identifies the relationship to ask_pipeworx, explains the beta's purpose, notes current state, and gives usage direction. The date and comparison details are somewhat specific but help set expectations. No fluff; efficient for the nuance conveyed.

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 as a variant router, the description covers the key aspects: what it is, how it relates to the stable sibling, when to use it, and that it's functional. It doesn't mention output shape, but since no output schema exists and the description says the response shape is identical to ask_pipeworx, that's sufficient. Overall, it's complete for an agent to decide and use 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 input schema covers all parameters with descriptions (aliases for 'question'), so high coverage. The description doesn't add parameter details but that's unnecessary since the schema is self-sufficient. It correctly states the request shape matches ask_pipeworx, which is enough context.

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

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

Description clearly states it's a beta version of ask_pipeworx, a universal router with the same arguments and response shape Mend for asking natural-language questions. It explicitly names the stable sibling (ask_pipeworx) and distinguishes the beta by its live routing-improvement candidacy, so an agent knows exactly what this tool is and how it differs from alternatives.

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

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

Provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide merges, giving context for when choosing this beta is appropriate. It notes that currently no candidate is active, so behavior matches the stable version, which prevents misuse.

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

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

The description goes well beyond the readOnlyHint annotation by detailing the refusal mechanism with specific refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and the exact success return shape including evidence as a verbatim quote. It also discloses the extra LLM call cost, which annotations do not capture. 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 information-dense but every sentence earns its place: it opens with the core purpose, continues with how extraction works, specifies the return contract and refusal reasons, then provides usage scenarios and a cost tradeoff. The structure is front-loaded with the key differentiator ('hallucination-resistant') and flows logically.

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

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

Despite having no output schema, the description fully documents the return shape and refusal envelope, so an agent knows exactly what to expect. It also positions the tool against its primary sibling (ask_pipeworx) and clarifies cost behavior. For a complex grounding/refusal tool, nothing needed for correct selection or invocation 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?

The input schema has 100% description coverage, with the 'question' parameter and all aliases fully documented. The description adds context about how the question is used (routed to tools, arguments filled, answer extracted) but does not add parameter-specific semantics beyond what the schema already states. Baseline 3 is appropriate.

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

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

The description clearly identifies a specific verb+resource: it is an 'answer mode' that 'EXTRACTS the answer using ONLY what the tool result contains.' It distinguishes itself from the sibling tool ask_pipeworx by highlighting its hallucination-resistant, grounded extraction behavior with evidence quotes and explicit refusals. This leaves no ambiguity about what the tool does.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and the condition for choosing it: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is direct, actionable routing guidance.

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

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

The description goes far beyond the annotations (readOnly, openWorld, idempotent, non-destructive) by disclosing a wealth of behavioral details: resolver contract with match confidence and alternatives, low-confidence short-circuit behavior, closed-market handling, wide-spread illiquidity warnings, cancellation-rule parsing, fan-out logic, and news fallback mechanics. This is exceptional transparency and adds significant value beyond annotations.

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

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

The description is long but highly structured, using uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) which makes it scannable. The opening sentence is a clear, front-loaded summary. While dense, every section contributes operational detail that an agent needs for correct use, so the length is 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 bear the full burden of explaining return values. It does so comprehensively: response shapes for result.market, result.analysis, result.evidence, resolver contract fields, parent_event extractor, news fallback fields, and status codes for low-confidence and closed markets. Despite the tool's complexity, the description leaves no significant gap.

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

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

The schema already provides full documentation (100% coverage) for all three parameters, so the baseline is 3. The description adds value by giving concrete examples for the 'market' parameter and explaining the default behavior and tradeoffs for 'depth' and 'include_raw' (e.g., recommended false to keep responses under ~20KB). This pushes it above baseline.

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

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

The description opens with a specific verb-resource pairing: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes this tool from siblings like polymarket_arbitrage or polymarket_edges by focusing on researching a single bet and returning an evidence packet. The purpose is 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 includes an explicit 'Use for' line listing three concrete query types: "should I bet on X", "what does the data say about Y", or "is there edge in Z". This gives clear when-to-use guidance. It does not explicitly mention when not to use the tool or name alternative tools, but the context is sufficient for an agent to select it appropriately.

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

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

Beyond the read-only and idempotent annotations, the description discloses detailed behavior: exact data sources (SEC EDGAR/XBRL, FAERS, FDA), specific metrics pulled, correct handling of off-calendar fiscal years, and result sorting by primary metric. It also mentions return of paired data with citation URIs, enriching the operational context.

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

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

The description is dense yet well-structured, opening with natural-language triggers, then defining the core function, and then detailing data sources and behavior. Every sentence contributes value with no filler, making it 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?

Given the absence of an output schema, the description effectively covers return format ('paired data + pipeworx:// citation URIs per entity') and sorting behavior. Combined with thorough annotations, it provides a complete operational picture for a tool with only two parameters.

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

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

The description adds substantial meaning beyond the schema: it explains that type determines which data set is retrieved (company vs. drug), provides concrete examples for values (e.g., tickers/CIKs vs. drug names), and clarifies metric-specific behavior. This goes well beyond the schema's enum and array constraints.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific trigger phrases and a distinct scope. It differentiates itself from single-entity tools like entity_profile by emphasizing the parallel comparison capability.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes that it replaces 8-15 sequential lookups, providing strong when-to-use guidance. This clearly positions the tool against 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 flag readOnlyHint=true, openWorldHint=truehol, and idempotentHint=true, so the safety profile is covered by structured hints. The description goes further, documenting the parallel decomposition behavior, the citations with stable pipeworx:// URIs present only when the source can be served by resources/read, the gaps[] field that guarantees no invented facts, the hop behavior, and the fact that large records are semantically excerpted. That's strong behavioral disclosure beyond the annotations. It doesn't cover failure modes like schema/API limits, timeouts, or partial failures at the tool level, but the annotations plus description give a reliable behavioral contract.

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

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

Long but dense. The account tier requirement and the alternative (ask_pipeworx) are front-loaded where they matter most. A couple of parenthetical asides could be trimmed, but nearly every sentence carries routing, behavior, or constraint 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 2-param tool with no output schema mensaje, the description fully compensates: it specifies what the packet contains (verbatim evidence + confidence + fetched_at + citation + gaps[]), how second-hop works, response time, tool-selection behavior up front, and the account tier gate. The agent can decide to call it and know what it will get back.

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?

Question param is self-evident, but the depth enum is explained with the number of facets and whether each adds a hop. The description clarifies what 'thorough' costs (paid) and what 'standard' adds (gap recovery) — value well beyond the enum labels 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?

Opens with a concrete verb+object ('research' across 5,581 structured tools), scopes what it covers (structured data, not open web), names the distinguishing mechanics (decomposition into facets, parallel routing), and explicitly contrasts with sibling tools (ask_pipeworx for breaking news / single lookups). An agent can tell exactly what this tool is for and when to prefer another one.

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

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

Gives precise selection conditions: account tier required, exact fallback (ask_pipeworx) for unauthenticated users anchored with a URL, and specific routing guidance for BREAKING/current news topics vs factual/structured queries. Also explains when second-hop depth is warranted. An agent can route correctly without needing to inspect ask_pipeworx.

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 return behavior: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This adds meaningful context about output and immediate usability.

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

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

The description is front-loaded with the core purpose and is information-dense. The list of domains is long but serves to inform the agent of coverage; no redundant text. Slightly verbose due to the domain enumeration, but 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 discovery tool with no output schema, the description covers purpose, when to use, return details (top-N, names, descriptions, schemas, examples), and the ready-to-call behavior. It also clarifies the scope via domain list and 'option set' guidance, making it complete for API-agent usage.

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

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

Schema description coverage is 100%, with all parameters (query, q, task, limit, search, description) documented with descriptions and aliases. The description itself does not add per-parameter semantics beyond stating query accepts natural language examples, which are already in the schema. 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: 'Find tools by describing the data or task.' It distinguishes itself from sibling tools by being a meta-search/discovery tool, enumerating covered domains and emphasizing 'no second schema lookup needed,' which differentiates it from direct data 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?

Explicit when-to-use guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set.' This gives clear direction for API-agent invocation, though no specific alternatives are named.

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/non-destructive annotations, the description discloses failure behavior ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), fallback logic (GDELT→GNews), and the parallel fan-out nature. It also details the exact return fields, adding significant context about what the agent will receive.

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 clause adds value: user intents, preference rule, output breakdown, failure modes, fallback, and parameter examples. It is well-structured with semicolon-separated lists, and despite its length, it remains focused 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 (multi-source aggregation, fallbacks, partial failures, multiple return fields) and no output schema, the description fully covers inputs, outputs, constraints, and behavioral edge cases. It leaves no critical ambiguity for an agent deciding whether 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?

The schema already provides full descriptions for both parameters (type and value), so baseline is 3. The description adds real-world examples ('AAPL', '0000320193'), reinforces the zero-padding requirement, and explicitly states the alternative route for names. This adds useful clarification beyond the schema.

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

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

The description opens with example user intents and a concrete definition: 'full cross-source profile of a US public company in ONE parallel call.' It clearly names the resource (US public company) and differentiates from siblings like resolve_entity and compare_entities by focusing on holistic cross-source profiling.

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 prefer this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names an alternative for unsupported inputs: 'use resolve_entity first if you only have a name' and gives parameter constraints.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, covering the safety profile. The description adds 'clear sensitive data' context but does not disclose behavior beyond what annotations imply, such as what happens if the key does not exist.

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

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

The description is two sentences, front-loaded with the core action, and every clause adds value (purpose, usage context, sibling relationship). No unnecessary 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 one-parameter tool with strong annotations, the description fully covers purpose, usage, and parameter meaning. No output schema is needed for a delete operation, and the description provides adequate context.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter. The description simply says 'by key,' which adds no additional meaning beyond the schema's 'Memory key to delete.'

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: 'Delete a previously stored memory by key.' This clearly distinguishes it from sibling tools like remember and recall, which store and retrieve memories respectively.

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 gives usage context: 'Use when context is stale, the task is done, or you want to clear sensitive data.' It also references related tools ('Pair with remember and recall'), but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the fetch-extract-emit process and the output format ('single text blob ready to drop at site-root/llms.txt'), which goes beyond annotation metadata.

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, information-dense, no filler. Front-loads the core purpose, then process, output, and use cases in a logical flow.

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 clearly explains the output format and use cases. Combined with annotations and full schema coverage, it provides enough context 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?

Schema covers 100% of parameters with clear descriptions for 'url' and 'max_links'. The description does not add parameter-specific details, but the schema descriptions are sufficient, 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 a specific action ('Generate a production-ready llms.txt file') with a resource ('for any URL') and process ('Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format'). It is easily distinguished from sibling tools, which focus on research or other AI visibility tasks.

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.' It does not name alternatives, but the tool is unique among siblings, so this is sufficient context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the agent knows it's a safe read. The description adds the specific data returned, which is useful, but it does not disclose further behavioral aspects like authentication requirements or rate limits, which the annotations do not cover.

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

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

The description is a single, front-loaded sentence that immediately states the verb 'Get' and the resource, followed by a compact list of returned items. Every word contributes value; there is no redundancy.

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

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

Given the simplicity (one parameter, read-only, no output schema), the description explains the key return elements (fields, geometry type, record count, capabilities), which is adequate for an agent to understand what to expect. It does not describe the exact format or any limitations, but that is not critical for a straightforward schema fetch.

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%: the 'url' property has a clear description and example. The tool description adds no additional parameter semantics beyond confirming that the URL is the input. Baseline 3 is appropriate since the schema fully documents the parameter.

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

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

The description clearly identifies the tool as retrieving an ArcGIS Feature/Map Service layer's schema via URL, specifying exactly what is returned (fields, geometry type, record count, capabilities). This distinguishes it from siblings like query_layer, which focuses on querying features rather than schema.

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

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

The description implicitly indicates this tool is for schema inspection by URL, which is clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, though the distinct purpose from sibling query_layer is implied.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable context by specifying the return fields and the 'caller's' scope, enhancing transparency beyond 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 three sentences: the first states the action, the second lists return fields, the third provides usage guidance. It is front-loaded, concise, and every sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides essential context: scope, return fields, and usage scenarios. Combined with strong annotations, it is fully complete for an agent to invoke correctly.

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

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

The only parameter, include_inactive, is fully documented in the schema (100% coverage), so the description does not need to add parameter-level detail. The description adds no extra semantic beyond the schema, making the baseline score of 3 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 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on listing. It also enumerates the return fields, making the purpose unmistakable.

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

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

Explicit guidance is provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly tells the agent when to use this tool (before subscribe/unsubscribe) and implicitly contrasts with alternatives like subscribe and unsubscribe.

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 the claim_token flow, rate limit (5 per identifier per day), free status, and daily-digest handling. It explains that filing without an account returns a token to check resolution status later. These behavioral details go well beyond the minimal annotation hints (readOnly=false, etc.) and are critical for correct execution.

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 lengthy, the description is tightly structured: purpose first, then usage triggers, exclusion, token workflow, and operational notes. Every sentence imparts actionable information, and the front-loading ensures the agent immediately grasps the tool's function. No filler or redundancy exists.

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 4-parameter tool with no output schema, the description covers the full workflow: when to report, what to include, the alternative path for other servers, the claim_token lifecycle, and rate-limiting. It addresses account-optional behavior and outcome tracking, making it sufficient for an agent to use correctly without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by illustrating the claim_token usage with a concrete example (`pipeworx_feedback({claim_token:"pwfb_…"})`) and by emphasizing specificity in message content. It does not fully map every parameter but the schema descriptions are already thorough, so the extra example earns 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 and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools by scoping it exclusively to Pipeworx tools and explicitly contrasting with filing bugs for other MCP servers. The purpose is unambiguous and differentiates from research/query siblings like ask_pipeworx.

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

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

Explicit when-to-use guidance covers bug, feature/data_gap, and praise with concrete trigger examples. It also provides an explicit exclusion: if the tool came from another MCP server, file with that server instead. The clarification 'Not sure? Pipeworx tool names are the ones this connection lists' gives a decision heuristic, making alternatives clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds valuable behavioral context: it aggregates from CF analytics-engine, includes no PII, returns only (pack, tool, count), and has a caching behavior (5min-1h depending on window). This goes beyond the annotations without contradicting them.

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

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

The description is moderately long but well-structured: it starts with a clear hook, then describes the output, then lists use cases, then adds caveats. Every sentence contributes value, and the format is easy to scan. Slightly verbose but appropriate for the information conveyed.

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 relatively simple tool with one optional parameter and no output schema, the description covers the return shape (top tools, top packs, total call volume), the data source, privacy (no PII), and caching behavior. It gives the agent enough to understand what it will get and when to use it. Missing details like exact response format are not critical given the absence of 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%, so the parameter is fully documented. The description adds interpretive meaning by explaining that shorter windows surface what's hot right now and longer windows show steady-state demand, which aids selection beyond the schema's simple enum.

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: showing what other AI agents are calling on Pipeworx, returning top tools, top packs, and total call volume. It uses a specific verb ('returns') and resource ('Pipeworx trending') and distinguishes itself from siblings like discover_tools by focusing on current usage trends rather than static discovery.

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

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

The description provides explicit use cases (discovering hot data sources, confirming canonical tool choice, aligning with agent needs), which give clear context for when to use the tool. However, it does not mention when not to use it or name alternative tools, so it falls short of full exclusionary guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral details: the fill check (realizable_edge_pp <= 0 means 'do not trade it'), the semantic anchor (≥0.30 Jaccard similarity), and partition filter (placeholder dropping). It explains what happens in edge cases.

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

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

The description is long but densely informative, with clear section separators (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, and the front-loading of purpose and modes makes it 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 and lack of output schema, the description thoroughly explains response structures ('opportunities[] (gap_pp, suggested_trade, reasoning...)'), internal logic, and safety checks, making it complete enough for an agent to understand when and how to call 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%, but the description adds substantial meaning: concrete examples of event slugs ('fed-decision-may-2026'), mentions that full URLs are accepted, and explains how topic mode works with seed questions. This goes beyond the schema's parameter descriptions.

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

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

The first sentence clearly states the tool's function: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It also distinguishes three modes (trending_scan, event, topic), making it distinct from siblings like polymarket_fill_risk which handles sizing.

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

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

Explicit guidance is provided: 'Call with NO args for a trending_scan', 'pass event for...', 'topic for...'. It even recommends when to use each mode and directs users to a sibling tool for custom sizing: 'For custom sizing use polymarket_fill_risk.'

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description substantially enriches this by detailing the three response segments, model families, per-opportunity fields like edge_pp_net and kelly_fraction, the 24h-move warning, diagnostics funnel counters, and KV-level caching keyed on knobs. It also explains why fed_candidates are excluded from ranking, providing deep behavioral disclosure 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 a dense wall of text with all-caps headers, nested parentheses, and extensive jargon. It is front-loaded with the core purpose, but the lack of structured formatting (bullet points, sections) and overwhelming detail hurt readability. While every sentence carries information, the overall size makes it not concise or 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?

With no output schema, the description must explain the return value and does so thoroughly: top-level by_segment{...}, fed_candidates/fed_note, and _diagnostics with funnel counters and filter_skips. It also explains why segments might be empty and covers caching behavior, making it highly complete for a complex tool with 9 parameters.

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

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

Though the input schema has 100% description coverage, the tool description adds crucial inter-parameter meaning: it explains that min_partition_leg_kelly applies to per-leg Kelly inside top_legs, why min_kelly doesn't filter partition arbs, and how min_liquidity/max_spread_pp act as tradeable-edge filters. This synthesis goes beyond the schema's individual parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further clarifies its niche with 'Built for "what should I bet on today"' and 'agents discover opportunities without paging hundreds of markets,' which distinguishes it from sibling tools like polymarket_arbitrage and 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 clearly states the intended use case ('what should I bet on today') and implies when to use it over alternatives by emphasizing it avoids paging hundreds of markets. It also provides guidance on knobs like min_liquidity and max_spread_pp to filter out unrealizable edges. However, it does not explicitly say when NOT to use this tool, so it stops 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.

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

The description extensively discloses behavioral details: data source dependency, snapshot TTL limits, gap behavior on cache-miss, and the fact that decay is computed from daily closes rather than intraday. These go well beyond the readOnly/openWorld/idempotent annotations.

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

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

The description is well-structured with sections (ARG, RESPONSE, LIMITS), front-loads the purpose, and every detail serves the agent's understanding. No filler or tautology.

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 (time-series, expired entries, snapshot gaps) and the absence of an output schema, the description fully documents the response fields, calculation details, and limitations. This is comprehensive for an agent to invoke and interpret correctly.

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

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

The schema already documents both parameters with defaults and constraints (100% coverage). The description's Args section reiterates defaults but adds no new semantic meaning beyond the schema, so baseline 3.

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

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

The description clearly states the tool's purpose with a specific verb phrase ('Edge persistence and decay telemetry') and directly distinguishes it from current edge snapshots by referencing daily polymarket_edges snapshots and the core question of edge age/decay. This differentiates it from sibling tools like polymarket_edges.

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

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

The description clearly implies the use case: analyzing edge age and decay across snapshots, contrasting fresh vs. old edges. It doesn't explicitly name alternative tools for current-edge queries, but the context is clear enough. Lacks explicit 'use X instead' guidance, so 4.

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

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

Goes far beyond the read-only/idempotent annotations by describing the actual behavior: ladder walking, top-of-book vs VWAP calculations, verdict states, per-leg fill details, thin-leg detection, and the dangerous partial-fill scenario in basket mode. This rich operational detail is exactly what an agent needs to trust the tool's outputs.

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

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

The description is dense and front-loaded, with clear SINGLE-MARKET/BASKET sections. Every sentence adds substantive value, but the length is substantial. For a tool with two distinct modes and an output schema, the detail is 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?

Given no output schema and four nuanced parameters, the description is remarkably complete. It enumerates all major return fields, explains both modes, gives concrete usage thresholds, and highlights the key risk scenario (partial basket fills becoming unhedged directional positions). An agent has sufficient context to parse results and decide when to invoke this 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?

Though the schema already covers 100% of parameters, the description adds significant mode-specific semantics: market vs event modes, side defaults (including auto-detection in basket mode), size_usd interpreted as max spend vs target proceeds, and basket settlement notional. However, it also says 'REQUIRES one of market or event' while the schema lists no required parameters, creating a minor contradiction between description and 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 a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly identifies the verb ('check'), the resource (Polymarket order books), and distinguishes itself from siblings by explicitly positioning it as a pre-trade validation for polymarket_arbitrage and polymarket_edges.

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

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

Provides explicit when-to-use context: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or polymarket_edges trade above ~$500. It explains the risk of theoretical overround on thin books and partial-fill directional exposure, but does not name specific alternatives when this tool should not be used.

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 goes well beyond by specifying exact conditions for compatibility_warning, temporal_alignment impact, skipped_cross_type/subtype counters, and emphasizes that pre-mapped does not guarantee tradeability. This adds substantial behavioral context without contradicting annotations.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and the first sentence states the core purpose. Most sentences earn their place by disclosing edge cases and response details, though a few phrases could be tightened without losing meaning.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure: per-venue prices, matched spread with top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It also covers likely failure modes and caveats, making the tool's behavior comprehensible 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?

The input schema covers all three parameters with 100% coverage, including allowed topic values and override semantics. The description adds value by explaining the two modes and clarifying that explicit tickers/slugs override the topic-mapped sides, which reinforces but does not duplicate schema content.

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

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

The description clearly identifies the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools by emphasizing the cross-venue comparison and the two input modes, making its purpose unambiguous.

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

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

The description explicitly defines two modes (topic shortcuts vs. explicit ticker/slug pairings) and provides guidance on when each is appropriate. It also warns that most pre-mapped topics may return compatibility_warning, earning context for when the tool may not be useful, though it does not explicitly name alternative sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details: 'Returns attribute rows (and geometry)' and a practical sampling technique, which go beyond the annotations and help set expectations for output.

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

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

Four short sentences, each earning its place: purpose, parameter summary, output shape, and usage tip. No filler or redundancy, and the most critical information is front-loaded.

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

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

The description covers source (search_datasets), all key parameters, return shape, and a sampling pattern. Combined with rich annotations, it is sufficient for a read-only query tool. Minor gaps like pagination semantics and possible errors are not critical given the schema coverage.

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

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

Schema coverage is 100% with descriptions and examples, so baseline is 3. The description adds value by summarizing the parameter syntax (SQL-like where, comma-separated out_fields) and highlighting the where='1=1' + out_fields='*' combination, enhancing practical 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 states a specific action ('Query an ArcGIS Feature Service / Map Service layer by its url'), names the exact resource, and references search_datasets as the source. This clearly distinguishes it from sibling tools like search_datasets (discovery) and layer_info (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?

Provides clear context by indicating the URL comes from search_datasets, implying a workflow. Also gives a concrete usage tip: 'Use where="1=1" + out_fields="*" to sample.' However, it does not explicitly state when not to use or name alternatives like layer_info.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the dual behavior of retrieving vs. listing, which goes 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?

Three concise sentences: first states the core action, second explains the use case, third provides scoping and sibling relationships. Every sentence earns its place, with no redundant information.

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

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

The tool is simple with strong annotations. The description covers the main behavior, optional parameter, scoping, and relationships with remember/forget. Given the absence of an output schema, it does not need to detail return values. Adequate for an agent to use 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 the description reinforces the 'omit to list all keys' behavior. It adds memory-pairing context (saved via remember) but does not introduce fundamentally new parameter semantics beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys. It uses specific verbs ('Retrieve', 'list') and names the related sibling tools, distinguishing this from other memory 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?

Provides a clear use case: look up previously stored context without re-deriving it. Explicitly mentions pairing with remember and forget, though it lacks an explicit 'when not to use' statement. The context is strong, but not fully exhaustive.

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

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

Goes beyond the readOnly and idempotent annotations by explaining the return payload (source, citation_uri, raw event payload), the mark_read side effect on subsequent calls, and the external feed endpoint. This adds significant behavioral context without contradicting annotations.

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

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

Three efficient sentences front-load the core purpose and then quickly cover details. Every sentence contributes useful information with no redundancy.

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

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

Without an output schema, the description adequately explains the return format, filter capabilities, the read-state mutation, and an alternative scriptable endpoint. This is complete for a read-oriented polling tool with good annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving an example type ('sec_8k'), clarifying 'since' as an ISO timestamp, and explaining that mark_read:true causes future calls to return only newer events. This enhances understanding beyond the schema.

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

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

The description opens with a specific verb and resource: 'Pull fired events from your subscription feed.' It further clarifies the return fields and filter options, which distinguishes it from sibling tools like list_subscriptions and recent_changes.

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 polling suitability. Mentions an alternative access method via a direct URL, but does not explicitly contrast with sibling tools like recent_changes or list_subscriptions, so it lacks explicit 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 discloses detailed behavior beyond the annotations: it fans out to SEC EDGAR, uses GDELT→GNews fallback (including when fallback triggers), and mentions USPTO soft-fails until reactivated. It also specifies the return structure (changes[], total_changes, citation URIs) and parameter formats, which annotations do not cover.

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

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

The description is dense with information but every sentence contributes: opening query examples, core function, fan-out details, since formats, return format, and alternative tool. It is front-loaded with purpose, then details, then guidance, and avoids any 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?

Despite having no output schema, the description fully explains the return value ('structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'). It also covers input formats, data sources, fallback behavior, and failure modes, making it self-sufficient for a complex data-fetching tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra value by giving concrete examples for 'since' ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. It also clarifies that 'value' can be ticker or CIK, matching but slightly enhancing 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 immediately defines the tool as a 'change feed for a company in the last N days/weeks/months' with concrete examples like 'updates on Acme' and 'news on Tesla recently'. It clearly states the verb (fetch/lists changes) and resource (company), and distinguishes itself from entity_profile by naming the alternative.

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 via natural language query examples and the phrase 'in ONE parallel call'. It also gives a direct when-not-to-use instruction: 'Use entity_profile instead when you want the static profile... regardless of window.' This meets the explicit alternatives criterion.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds meaningful behavioral context: key-value scoping by identifier, persistence differences between authenticated (persistent) and anonymous sessions (24 hours), and that it stores data for reuse. This enriches the agent's understanding without contradicting annotations.

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

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

The description is concise (three sentences), front-loaded with the core purpose, and follows with usage guidance and behavioral details. Every sentence earns its place with no redundancy or filler, making it easy to parse and understand.

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-parameter tool with no output schema, the description is complete. It covers what the tool does, when to use it, how data is stored (key-value, scoped, persistence details), and how it relates to sibling tools (recall, forget). No critical information is missing for an agent to invoke it correctly.

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

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

The input schema already covers both parameters with clear descriptions and examples (e.g., 'subject_property', 'target_ticker'), achieving 100% schema description coverage. The description's mention of key-value pairs and example usage adds context but does not provide significant additional parameter-specific semantics beyond what the schema already offers.

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

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

The description clearly states the tool's purpose with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It distinguishes itself from sibling tools by explicitly mentioning recall and forget for retrieval and deletion, making its role unique.

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

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

The description provides explicit usage guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address, user preference). It also references alternatives by noting 'Pair with recall to retrieve later, forget to delete,' clarifying when this tool should be used versus siblings.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses cascading internal lookups, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR still returns), and that unresolved identifiers are listed explicitly under an 'unresolved' field. 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 efficiently packed with value. The first sentence captures purpose with examples, followed by a clear usage cue, then structured details per type. Every sentence adds information; no filler. Slightly verbose but justified by 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?

Given the tool has only 2 parameters and no output schema, the description is remarkably complete. It explains the return payload for each type, graceful degradation, source labels, and the 'unresolved' field. An agent can confidently use the tool without needing to guess behavior.

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

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

Schema coverage is 100%, but the description adds extensive meaning: for company type, it explains the full set of returned identifiers (CIK, ticker, LEI, FIGI) and how ISINs resolve to legal entities. For drug type, it mentions RxCUI and citation. This far exceeds the schema's brief 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 specific example queries like 'What's the ticker for…' and clearly states it resolves a name to canonical identifiers. It explicitly says 'Use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools like entity_profile or deep_research.

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 instructs to use this tool first when needing an ID from a name. It also notes that it replaces 2-3 manual lookups, implying it's the go-to for entity resolution. It does not explicitly state when not to use it, but the context is clear.

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

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

The description adds behavior beyond annotations: it probes each entity with ai_visibility_check, treats the first entity as the 'subject' for narrative, and returns score/confidence/signal density. Annotations already declare read-only/idempotent, so the description need not repeat safety. It doesn't mention rate limits or external API side effects, but the schema covers the _apiKey aspect.

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 purpose, then mechanism, then use case, then output format. No wasted words; every sentence adds value.

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

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

Despite no output schema, the description explicitly lists return fields (score, confidence, signal density) and the ranking behavior. It also orients the reader with the competitive audit context. Combined with strong annotations, this is fully adequate 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?

Schema coverage is 100% with good parameter descriptions. However, the description adds crucial semantics: entities must be 2-8, the first entry is the 'subject' and the rest are competitors, and context disambiguates common names. This goes beyond the schema's generic array description.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from the single-entity sibling ai_visibility_check. It also states the output (ranked list, most/least recognized) and mentions the mechanism (probes with ai_visibility_check).

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

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

Provides a concrete use case ('competitive AI-marketing audits') with an illustrative query ('does Claude know about us as well as our competitors?'). It implies when to use (multi-entity comparison) but does not explicitly state exclusions (e.g., 'if you only need one entity, use ai_visibility_check').

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

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

Annotations already mark read-only/idempotent, but the description adds critical runtime behavior: it fans out to two external services, notes a 5-30s first-measurement delay, and explains graceful partial failure with sources_failed. This goes well beyond the annotation's simple safety hints and prepares agents for realistic edge cases.

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

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

The description is dense but well-structured, leading with the composite action, then usage guidance, return summary, ecosystem caveat, and failure behavior. While longer than the two-sentence ideal, every sentence carries necessary information without redundancy, and it 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?

No output schema exists, but the description enumerates the summary block fields, per-advisory detail, links, alternative versions, and failure mode. This gives an agent accurate expectations for return payload and external behavior, making the tool fully actionable in one go.

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

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

Schema covers both parameters at 100%, including scoped package support and version defaulting. The description adds little beyond the schema—it mentions 'recent alternative versions' and ecosystem scope, but doesn't clarify parameter usage beyond what the schema already states, 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 opens with a specific verb and resource: 'Composite "should I add this npm package to my project" check in ONE call,' naming exact data sources (deps.dev, bundlephobia) and what it assesses. This unambiguously differentiates it from sibling tools like scan_competitor_ai_presence by focusing on npm dependency evaluation.

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 it ('Use whenever an agent asks...') with concrete example queries. Also gives an exclusion rule: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' helping agents choose the correct tool for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context by specifying what the tool returns (name, summary, record_count, owner/org, url) and how the output should be used, going beyond the structured 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 two sentences, front-loaded with the purpose, and every clause earns its place. It is concise, yet packs in the scope, returns, and downstream usage without unnecessary verbiage.

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 fully covers the expected return fields and how to use the result (pass url to query_layer/layer_info). This is sufficient for a search tool, and the sibling context doesn't introduce missing requirements. Comprehensive enough for tool selection and invocation.

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

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

The input schema already covers all three parameters with descriptions (coverage 100%), so the baseline is 3. The description does not add additional parameter-specific semantics, but the return-value explanation and workflow hint provide some context beyond the schema. No major 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 clearly states the verb 'Search' with a specific resource ('Fairfax County GIS open geospatial datasets') and gives useful category examples. It also distinguishes itself from sibling tools by mentioning the chain to query_layer / layer_info, making its role in the tool ecosystem explicit.

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

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

The description implies the primary use case: finding datasets by keyword and then passing the returned URL to query_layer or layer_info. It does not explicitly list exclusions or alternative tools, but the chaining instruction provides clear context for when to use this tool.

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

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

The description discloses technical behavior beyond the annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)'. This adds valuable context about how the search works and its limitations, which annotations alone do not provide.

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

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

The description is well-structured and front-loaded: it states the purpose first, then usage guidance, then companion tools, then technical details. Every sentence earns its place; there is no fluff or repetition of schema 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?

The description is self-sufficient despite having no output schema. It explains the return format ('top-N passages with character offsets and similarity scores'), the truncation behavior, and the embedding/window details, giving the agent a complete picture of what to expect.

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 extra meaning with concrete examples for the text parameter ('e.g. a SEC 10-K body, an article, a long tool result') and for the query parameter ('supply-chain risk', 'fiscal year 2024 revenue'), which helps the agent understand expected input formats 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 'Semantic search INSIDE a fetched record', clearly stating the specific action and scope. It distinguishes itself from siblings like ask_pipeworx_grounded (which grounds over a whole document) and search_datasets (which searches datasets) by emphasizing the 'inside a fetched record' constraint.

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

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

It explicitly states 'Use when the record is too big to cram into the prompt', giving a clear when-to-use criterion. It also mentions 'Pairs with ask_pipeworx_grounded', providing a complementary alternative and usage context, which helps the agent decide between 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?

The description discloses substantial behavioral traits beyond the annotations: OAuth account requirement for persistence, phone verification and 10/day SMS cap, webhook HMAC signing and one-time secret, auto-disable after 10 failed runs, and always-on feed behavior. This is far richer than the annotation fields alone.

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

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

The description is front-loaded with the core purpose, then organized into 'Supported types' and 'Delivery channels' sections. It is lengthy but each segment provides necessary operational detail; the length is justified by the tool's complexity, though it could be tightened.

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

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

The description is rich but incomplete: it lists only three of the five subscription types (omitting patent_grant and clinical_trial) and its delivery channels overview omits webhook, which is present in the schema. These omissions could mislead an agent into thinking those options don't exist, so the description is not fully complete for this complex tool.

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

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

While the schema already has 100% coverage, the description adds semantics for several types (e.g., items:["5.02"] = officer change, topic:"fed") and elaborates on delivery details like HMAC signing. However, it omits two schema types (patent_grant, clinical_trial), so it doesn't add meaning for every parameter.

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

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

The description opens with a specific verb and resource: 'Create a proactive monitoring subscription to a live-data event stream' and clearly states the return value ('Returns the new subscription id'). It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by emphasizing creation of new subscriptions.

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

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

The description provides clear context for use, such as OAuth requirements and delivery channel options, and hints at how to consume the feed via recent_alerts or the registry URL. It lacks explicit 'when not to use' or direct alternative naming, but the context is unambiguous.

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, and non-destructive. The description adds valuable behavioral context beyond annotations: it returns dynamically sourced example questions with exact tool call shapes, supports optional topic focus or full spread, and mentions the live catalog. This is rich disclosure for an onboarding tool.

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 structured with a front-loaded intent phrase, then core behavior, call patterns, and when-to-use. It is somewhat lengthy due to the repeated example queries ('what can you do?', 'give me ideas'), but each part contributes to intent matching for an AI. It is compact enough for the tool's simple 1-param interface.

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 carries the burden of explaining return values—it does: 'Returns category-bucketed example questions ... each with the exact tool + argument shape.' It also covers both call patterns (with/without topic) and the intended usage context. For a 1-optional-parameter tool, this is complete.

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

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

The schema already documents the optional `topic` parameter and its allowed values, including the omit behavior. The description adds meaning by explaining that passing topic 'focuses' results and omitting gives 'the full spread,' plus concrete examples ('finance', 'pharma', 'betting'). It reinforces but doesn't significantly expand beyond schema.

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

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

The description clearly identifies the tool as 'the onboarding entry point' that returns category-bucketed example questions with exact tool+argument shapes. It uses a specific verb ('returns') and resource ('example questions from the live catalog'), and distinguishes it from siblings by focusing on discovery of 'what to ask' rather than executing queries.

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

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

It gives explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also implies when-not-to-use (if you already know). However, it does not explicitly name alternative sibling tools (e.g., discover_tools) for those with clearer goals, so a small gap remains.

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 rather than deleted, preserving historical events in recent_alerts, and that ownership is enforced. This adds meaningful behavioral context for the agent.

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

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

The description is concise and front-loaded: two sentences that state purpose, a constraint, and the side effect without any redundant 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 one-parameter tool with no output schema, the description covers all essential aspects: what it does, who can use it, and what side effects occur. It fully equips an agent to select and invoke it correctly.

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

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

The input schema fully documents the single 'id' parameter with a clear description referencing subscribe. The tool description only repeats 'by id' and adds no extra parameter semantics, 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 ('Cancel a subscription by id') and the resource ('subscription'), distinguishing it from siblings like subscribe, list_subscriptions, and recent_alerts. It also adds the ownership constraint, which reinforces the specific scope of this 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 gives clear context for when to use the tool (cancelling a specific subscription) and the ownership limitation, but it does not explicitly point to alternatives or say when not to use it. The contrast with subscribe and list_subscriptions is implied rather than stated.

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 read-only/idempotent/open-world, the description adds critical behavioral details: the two verification paths, the exact verdict enum, the meaning of could_not_verify as 'check did not happen' with verification_error, and the 'unsupported' meaning. It also explains that returns include a grounded actual value with citation and reasoning. This exceeds the annotations significantly.

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 front-loaded: it opens with user phrasings, defines scope, explains the branching logic, lists outputs, includes a critical caller warning, and ends with an efficiency note. Every sentence conveys essential selection/invocation info; no fluff.

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

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

The tool is complex (two pipelines, six verdicts, a critical error semantics), and the description covers all of it: input type, output structure, verdict meanings, source routing, and caller caveats. With no output schema, the description fulfills the return-value explanation role. The only minor omission is tolerance_pct behavior, but that is fully 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 coverage is 100% (both claim and tolerance_pct have descriptive schema text including examples and default behavior). The description only reinforces that claim is a natural-language factual claim and adds no new parameter-level information. Baseline 3 applies due to full schema coverage.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit verbs like 'fact check', 'verify', 'confirm/refute'. It distinguishes from siblings by returning verdicts and covering both structured financial and grounded pipeline claims, and notes it replaces 4–6 sequential calls, giving it a unique role.

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

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

Provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (SEC EDGAR/XBRL fast path) and other claims (grounded pipeline). However, it lacks explicit 'when not to use' guidance or named sibling tool alternatives, 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.