Arcgis Linncounty

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

Annotations already mark the tool as read-only and idempotent, and the description adds meaningful context: default model is free, Anthropic requires a BYO API key with direct payment, and the response structure is outlined. It also explains the probing nature 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 main action, and each sentence adds essential information: what it does, how pricing works, and return format. No wasted words.

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

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

Despite no output schema, the description specifies the per-model return structure and combined view, covering the key result details. Combined with complete parameter docs and annotations, the tool is well-specified for an agent to use effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the cost implications of '_apiKey' and the default model behavior, going beyond the schema's straightforward parameter descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge and scores visibility (0-100), which is specific and distinct from generic querying. However, it does not explicitly name sibling alternatives like 'scan_competitor_ai_presence' or 'ask_pipeworx', so it falls short of full differentiation.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving context for when to use it. It does not explicitly state when not to use it or mention alternatives, so it lacks the exclusions needed for a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering safety. The description adds meaningful behavioral context: it routes to a large repository, automatically fills arguments, returns stable pipeworx:// citation URIs, and is a single fast call. 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 front-loaded with the key directive ('PREFER OVER WEB SEARCH') and then provides detailed use cases and examples. It is somewhat long and repetitive (e.g., 'START HERE', 'default entry point'), but the structure is logical and every section adds value. Not maximally concise, but well-organized.

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

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

The description is complete for a complex meta-tool: it explains the routing mechanism, return format (structured answer with citation URIs), and how it relates to sibling tools. With no output schema, the description appropriately covers return values and usage scope, leaving no major gaps for an agent to mis-invoke the tool.

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

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

The input schema has 100% coverage, documenting the 'question' field and all its aliases. The description provides examples but does not add new parameter-level meaning beyond what the schema already states. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: it routes questions to one of 5,462 tools across 1419 verified sources and returns structured answers with citation URIs. It also distinguishes from siblings by explicitly naming ask_pipeworx_grounded and deep_research for different use cases, making the core function 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 provides explicit guidance on when to use this tool versus alternatives: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named siblings for grounded answers or multi-part research. It also lists concrete example queries, making the usage context very clear.

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

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

The description goes beyond annotations by revealing the experimental nature, current inactive candidate status (retired 2026-07-26), and exact equivalence to ask_pipeworx, including the same 5,462 tools and response shape. It also states there is no fallback, reinforcing that it is a fully working router.

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 with no wasted sentences: it names the beta relationship, current state, usage instruction, and a clarification that it is not a fallback. Each sentence earns its place and key details are 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?

For a router with no output schema, the description provides sufficient context: current status, equivalence to stable tool, comparison purpose, and reassurance that it is a full router. Combined with complete schema and annotations, the description is fully adequate.

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

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

The input schema already documents all parameters and aliases, so the description adds no parameter-level detail beyond referencing that arguments are identical to ask_pipeworx. Baseline of 3 applies since schema coverage is 100%.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with an identical tool set, arguments, and response shape. It distinguishes itself from the sibling ask_pipeworx by noting candidate routing improvements, though it does not state the router's core function in explicit terms.

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 usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. It does not enumerate alternatives or exclusion criteria, but the distinction from the stable variant 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 goes far beyond the annotations by detailing the refusal reasons (not_in_source, no_tool_match, etc.), the evidence verbatim quote, the cost of one extra LLM call, and the strict 'only what the tool result contains' behavior. Annotations only indicate readOnly/idempotent, so the description adds substantial behavioral context.

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

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

The description is well-structured, front-loaded with the core purpose, and every sentence adds relevant detail. It is somewhat long due to the enumeration of refusal reasons and return shapes, but these are necessary for a tool with no output schema.

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

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

The tool is complex with a detailed return object and refusal semantics. The description fully explains the success and failure shapes, when refusals occur, and the cost trade-off vs ask_pipeworx. Without an output schema, the description carries this burden and does so completely.

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 clear descriptions for the question field and its aliases. The description adds no extra parameter-level meaning, so the baseline of 3 applies.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' that routes to tools, fetches data, and extracts answers using only the tool result. It explicitly distinguishes itself from ask_pipeworx by emphasizing the extra LLM call and refusal mechanism, making its purpose unambiguous.

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

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

It provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This both states when to use this tool and when to use the alternative, satisfying the when/why-not requirement.

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 readOnly/openWorld/idempotent hints by detailing the resolver contract (market_match_confidence, alternatives), safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquidity warnings, and cancellation-rule risk. This is rich behavioral context that annotations 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 long but well-structured with clear section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded intent. Every section provides useful operational detail, though some fan-out examples are extensive; still, they are relevant for teaching the agent how the tool behaves.

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

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

With no output schema, the description fully carries the burden of explaining return values. It describes the shape of result.market, result.analysis, result.evidence, the resolver contract, parent_event extractor, news fallback fields, and status codes, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% and each parameter already has a description. The tool description adds value by explaining how the market parameter is interpreted (slug, URL, or question text) and gives concrete fan-out examples that clarify the impact of the market input. It does not discuss depth or include_raw, but those are already well-described 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?

The description opens with a clear, specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from siblings like polymarket_arbitrage or validate_claim by focusing on evidence-gathering and market-vs-model comparison for a single bet.

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

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

The description explicitly states when to use the tool: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'." It does not mention when not to use it or point to alternatives, but the use cases are clear and distinct from sibling tools.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context beyond that: it details the data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), the specific financial metrics pulled, the sorting by primary metric, and the return of paired data with citation URIs. It also mentions correct handling of off-calendar fiscal years, which is a non-obvious behavior. No contradictions with annotations.

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

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

The description is longer than the minimum but every sentence serves a purpose. It front-loads the core action with example triggers, then covers data sources, type-specific behavior, sorting, and return format. The only minor issue is that 'ALWAYS PREFER' guidance could be slightly more concise, but overall it is well-structured and scannable, with 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?

With no output schema, the description carries the burden of explaining return values, which it does by stating 'Returns paired data + pipeworx:// citation URIs per entity.' It also covers the scope (2-5 entities), the data metrics, sorting behavior, and the number of sequential lookups it replaces. Given the tool's complexity, this description is thorough and leaves little ambiguity for an AI agent.

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

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

Schema coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds value by explaining the values parameter with examples (tickers/CIKs vs drug names) and clarifying type-specific behavior. It also notes that results are sorted by primary metric, which informs how the parameters affect output. While not exhaustive, it goes beyond the schema and helps the agent construct valid inputs.

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: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific verbs ('compare', 'rank', 'side-by-side') and specifies the resource types, distinguishing it from siblings like entity_profile by emphasizing parallel comparison over sequential lookups. It also gives concrete example triggers, making the purpose unmistakable.

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

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

The description explicitly tells when to use this tool: whenever the user asks to compare entities, and it says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' This differentiates it from entity_profile or single-entity lookups. It also provides guidance on type-specific behavior (company vs. drug) and notes that off-calendar fiscal years are handled correctly, setting expectations for usage across different entity categories.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial operational context: account requirement, paid tier for 'thorough', latency expectations, explicit 'never invented' behavior via gaps[], and that citation_uri is only present when fetchable. This goes well beyond structured 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?

The description is long but every major clause earns its place: authentication, alternatives, output packet format, depth differences, latency, and limitations. It is logically ordered and front-loaded with the most critical gating information (account requirement and fallback tool).

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?

Since there is no output schema, the description fully specifies the return envelope: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers failure modes and timing, making it complete for a tool of this complexity.

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

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

Input schema already provides 100% parameter coverage with a detailed explanation of each depth value, so the baseline is 3. The description adds extra semantics about paid-tier implications, gap-recovery hops, contradictions[], and citation fetchability, raising it to 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?

Description clearly defines the verb and resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' with explicit contrast to open-web search. It also distinguishes the tool from siblings by emphasizing decomposition into facets and parallel routing across 5,462 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 explicit usage boundaries: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It even advises using ask_pipeworx when not signed in, making selection criteria 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 readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context by disclosing that it returns top-N tools with full input schemas ready for direct invocation, eliminating the need for a second lookup—information 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 front-loaded with the core purpose and is organized in three sentences. The second sentence is a long enumeration of domains, but each element is purposeful and the overall length is reasonable for a discovery tool.

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

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

For a read-only search tool with no output schema, the description adequately covers purpose, usage scenarios, return format, and the self-contained nature of results. It gives sufficient context for an agent to decide when and how to use the tool.

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

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

Schema description coverage is 100%, with all six parameters documented, establishing a baseline of 3. The description mentions natural-language querying and the limit parameter but does not add significant semantic meaning beyond what the schema already provides.

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

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

The description opens with 'Find tools by describing the data or task,' a specific verb+resource combination that clearly states the tool's purpose. It further distinguishes itself from the many sibling tools by positioning as a discovery meta-tool and instructing to 'Call this FIRST.'

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 you need to browse, search, look up, or discover what tools exist' and lists specific data domains, giving clear context. It also provides explicit guidance to call this first when many tools are available, effectively differentiating from 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: USPTO patents API sunset soft-fails, names not supported, cross-source fan-out details, and a specific breakdown of returned data (CIK, filings, fundamentals, patents, news, LEI). 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 every sentence carries weight: user examples, fan-out details, return structure, and failure modes. It is front-loaded with illustrative prompts. Slightly dense but appropriate 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?

With no output schema, the description comprehensively enumerates return fields (CIK, filings with URIs, fundamentals, patents, news, LEI), explains limitations (names not supported, USPTO sunset soft-fail), and covers input constraints. It is fully self-contained for an agent to select and invoke correctly.

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

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

Schema covers both parameters with descriptions and enum. The tool description goes further by giving concrete examples ('AAPL', '0000320193'), clarifying zero-padded CIK format, and re-emphasizing that names are not supported. This adds practical value 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 it creates a 'full cross-source profile of a US public company' in one call, with specific examples of user intents. It explicitly distinguishes from chaining single-pack SEC/XBRL/news lookups, making its purpose and scope unambiguous.

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

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

Explicitly instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also directs users to resolve_entity first if only a name is available, providing clear when-to-use and alternative guidance.

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

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

Annotations already declare destructiveHint and idempotentHint, so the bar is lower. The description adds context that deletion targets 'previously stored' memories and is used to clear sensitive data. It doesn't provide details on error handling or permissions, but annotations cover the key safety traits.

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

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

Two sentences, immediately states the action and usage. 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?

A simple one-parameter destructive tool with rich annotations and a full schema description. The description provides purpose, when-to-use, and complementary tools, making it sufficient without an output schema.

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

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

Schema description coverage is 100%—the single 'key' parameter is fully described as 'Memory key to delete'. The description doesn't add extra parameter semantics beyond that, so baseline 3 is appropriate.

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

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

Clearly states 'Delete a previously stored memory by key' with a specific verb, resource, and mechanism. Distinguishes from siblings remember and recall by indicating deletion vs storage/retrieval.

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

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

Explicitly lists when to use: stale context, task done, clearing sensitive data. Also recommends pairing with remember and recall, and the sibling list includes those tools, providing clear 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, idempotentHint=true, and destructiveHint=false, giving the agent a safe read-only profile. The description adds valuable behavioral context: it performs a network fetch of the URL, extracts specific fields, and returns a text blob ready for site-root placement. This goes beyond the annotations but does not cover potential issues like timeouts or page fetch failures, so a 4 is appropriate.

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

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

The description is three sentences plus a use-case list, all highly informative. It front-loads the core purpose and process, then gives output context and use cases. No redundant or filler language; every sentence earns its place.

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

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

Given the tool's moderate complexity and the lack of an output schema, the description adequately explains what the output is (a text blob) and where it is meant to be placed (site-root/llms.txt). It also covers the process, scope (any URL), and typical use cases. It does not discuss edge cases like malformed URLs or large sites, but these are not essential for invocation. Sibling context further clarifies its role.

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

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

Both parameters (url and max_links) have rich schema descriptions covering 100% of the parameter space. The description adds minimal parameter-specific detail beyond saying 'any URL' and mentioning 'standard llms.txt markdown format,' but it does not explain how max_links relates to the output or how the URL should be formatted beyond the schema's example. With full schema coverage, a baseline of 3 is justified.

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

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

The description opens with a clear verb and resource: 'Generate a production-ready llms.txt file for any URL.' It then briefly explains the process (fetches page, extracts title/description/key links) and the output (standard llms.txt markdown). This distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check because it is specifically about producing the llms.txt file, not just auditing AI presence.

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 lists three use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing a competitor's AI visibility. These are clear, actionable contexts. However, it does not state when NOT to use this tool or mention alternative sibling tools (e.g., scan_competitor_ai_presence) for auditing, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds the specific return payload (fields, geometry type, record count, capabilities) but does not mention network dependencies, error handling, or rate limits—context that would be valuable for a read-only external call.

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, information-dense sentence. It front-loads the core purpose ('Get an ArcGIS Feature/Map Service layer's schema by url') and efficiently lists the included items with no wasted words or redundant phrasing.

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

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

For a simple tool with one parameter, a fully descriptive schema, and strong annotations, the description is sufficient. It clearly states what the tool returns, which compensates for the lack of an output schema. No additional context is necessary for effective use.

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

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

Schema description coverage is 100%, with the 'url' parameter clearly documented in the input schema. The description reinforces 'by url' but adds no extra semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get'), identifies the resource ('ArcGIS Feature/Map Service layer's schema'), and provides a precise scope by URL, listing exact return contents (fields, geometry type, total record count, capabilities). While it doesn't explicitly name sibling tools, 'schema' clearly differentiates it from data-returning tools like query_layer.

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 no guidance on when to use this tool versus alternatives such as query_layer. It doesn't mention typical use cases, prerequisites, or scenarios where this tool is preferred, leaving the agent to infer usage solely from the description.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds meaningful context: it lists the caller's subscriptions (scoping), returns specific fields including fire_count, and defaults to active only. This enriches understanding 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?

Three concise sentences with no filler. The first states the purpose, the second lists return fields, and the third gives usage guidance. 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?

Given the tool has only one optional parameter and no output schema, the description compensates well by enumerating return fields. It also provides usage context and relies on accurate annotations for safety. The information is complete for 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?

Schema coverage is 100% for the single optional parameter include_inactive, and its description in the schema is clear. The tool description does not add parameter details, but the schema already carries the meaning, so a baseline of 3 is warranted.

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

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

The description clearly states the action ('List') and the resource ('the caller's active subscriptions'), with a specific verb and scope. It also distinguishes from sibling tools like subscribe/unsubscribe by noting it reviews current monitoring and supports cancellation by finding an id.

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

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

The description explicitly tells when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies alternatives (subscribe/unsubscribe) but does not name them explicitly, so a 4 is appropriate.

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

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

The annotations are all false and provide no behavioral hints, so the description carries the full burden. It discloses the claim_token flow, rate limiting ('5 per identifier per day'), that reporting is free and doesn't count against quota, and the privacy-relevant instruction not to paste end-user prompts. This is rich behavioral context beyond the structured fields.

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

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

The description is longer than the two-sentence ideal, but every sentence earns its place: purpose, trigger conditions, boundaries, claim_token mechanics, rate limit, and cost. It is well-front-loaded and logically organized, though it could be tightened slightly without losing essential 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?

Despite having no output schema, the description explains the key return behavior (claim_token) and the follow-up reading workflow. It covers edge cases (external MCP servers), addresses the feedback scope, and provides rate-limit and cost context. This is complete enough for an agent to select and invoke the tool correctly with confidence.

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 all parameters are already described. The tool description adds significant value for the claim_token parameter by detailing exactly how to use it ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed'), which is more actionable than the schema text. It also clarifies the context object is optional.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the feedback categories (bug, feature, data_gap, praise) and clearly distinguishes itself from sibling tools like ask_pipeworx or discover_tools by framing this as reporting issues rather than querying.

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 triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a crucial exclusion (only for this Pipeworx connection, not other MCP servers) and guidance on what to include in the message.

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

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

Even with annotations providing readOnly, openWorld, idempotent, and non-destructive hints, the description adds valuable behavioral context: it explains the data source ('derived from CF analytics-engine'), privacy ('no PII'), output structure ('just (pack, tool, count)'), and caching ('Cached 5min-1h'). This goes beyond annotation defaults and gives the agent a richer understanding.

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

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

The description is a single well-structured paragraph with a clear lead statement, a list of use cases, and extra context about data source and caching. It is dense but all sentences contribute meaning. It would merit a 5 if it were more briefly worded, but the extra context is useful, so a 4 is fitting.

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

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

For a tool with one optional parameter and no output schema, the description is highly complete. It explains what the tool returns (top tools, top packs, call volume), the output structure (pack, tool, count), the data source, privacy characteristics, and caching behavior. No significant gaps remain 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 provides a full description of the 'window' parameter and its enum values. The tool description merely repeats these windows and adds no new semantic depth beyond what the schema states. With 100% schema coverage, the baseline of 3 is appropriate, as no additional parameter insight is provided.

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: 'Returns the top tools, top packs, and total call volume over a recent window.' It identifies the specific resource (Pipeworx trending data) and distinguishes itself from siblings by focusing on aggregate usage by other AI agents, a unique angle compared to discovery or search 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 explicit use cases: 'discovering what data sources are hot for current events,' 'confirming a popular tool is the canonical choice,' and 'seeing whether your use case aligns.' However, it does not explicitly mention when not to use this tool or name alternatives, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by detailing internal behaviors: semantic anchor with Jaccard threshold (≥0.30), partition filter with placeholder fraction >20% returning null, and fill check against live CLOB depth with specific edge thresholds (theoretical vs realizable at 1000 shares/leg). It also warns 'do not trade it' when realizable_edge_pp ≤ 0. 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?

Despite being lengthy, the description is well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a clear response format. The first sentence is a high-level summary, and every subsequent sentence adds operational detail. It is front-loaded with the most critical usage instruction (mode selection).

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

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

This is a complex two-mode tool with thresholds and filters, no output schema, and only two optional parameters. The description fully compensates by explaining the response fields (opportunities[], partition_check{...}), failure indicators (skipped_low_similarity, placeholders_filtered), and how to interpret and act on results (fill check, do-not-trade condition). It also points to a sibling tool for custom sizing, completing the operational 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%, but the description adds substantial meaning: it explains that `event` takes a Polymarket event slug with examples, `topic` is a seed question for cross-event scans, and clarifies that calling with no args triggers a trending_scan. It also differentiates the two modes semantically (single-event vs cross-event) beyond the schema's basic field descriptions.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly differentiates between the three modes (trending_scan, event, topic) and distinguishes itself from sibling tools by name (e.g., polymarket_fill_risk).

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 provides when to use each mode: 'Call with NO args for a trending_scan...', 'pass `event` for the strongest per-event partition_check', and 'topic for a themed cross-event scan.' It also names an alternative for custom sizing: 'For custom sizing use polymarket_fill_risk.' This gives clear when/when-not 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 indicate read-only, idempotent, and non-destructive behavior. The description goes far beyond by disclosing output structure, the partition-level kelly=0 quirk, diagnostic funnel counters, 24h-move warnings, and caching behavior ('Cached 1h at the KV level keyed on all knobs'). It also explains why Fed signals are unreliable at meeting-month horizons. No contradictions with annotations.

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

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

The description is a single dense paragraph, but it is well-organized with parentheticals and numbered segments. It front-loads the main purpose and then details models, response structure, knobs, and diagnostics. While not as scannable as bullet points, every sentence contributes substantive information, and the complexity warrants the length.

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

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

With no output schema, the description must explain the return structure, and it does thoroughly: top-level fields (by_segment, fed_candidates, _diagnostics), segment definitions, per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity), and diagnostic counters. It also explains why segments may be empty and how knobs affect results, making the tool's behavior fully 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?

Schema covers 100% of parameters with detailed descriptions, but the tool description adds valuable context beyond the schema. For example, it explains that min_kelly filters single-leg opportunities but not partition arbs, that slippage_pp should be bumped for thin books, and that min_liquidity prevents walking the book. This deeper rationale helps agents select and set parameters correctly.

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

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

Description explicitly states the tool's core function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further differentiates from siblings by naming response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and indicating its purpose as 'what should I bet on today' discovery, clearly separating it from tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description gives a clear use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains how knobs like min_liquidity, max_spread_pp, and category_filter tune behavior, and notes that Fed candidates are excluded from ranking. While it doesn't explicitly name alternative tools for different scenarios, the provided context is sufficient to imply when this tool is appropriate.

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

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

Annotations already mark this as read-only and idempotent, but the description goes much further by detailing the exact response structure (tracked, expired, snapshot_dates), the 60-day TTL limit, snapshot write behavior on cache-miss, gaps in data, and the computation basis (daily closes, not intraday). It even explains signing semantics (negative = SELL YES). 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 lengthy but well-structured with clear 'Args:', 'RESPONSE:', and 'LIMITS:' sections. Every sentence contributes useful information, such as the interpretation of expired opportunities and the meaning of snapshot gaps. It is dense but justified given 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?

With no output schema, the description fully specifies the response fields (tracked, expired, snapshot_dates), their contents, and the limitations (TTL, snapshot availability, data derivation). This gives an agent everything needed to correctly interpret and use the tool's results.

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

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

Schema coverage is 100% for both parameters, with detailed descriptions for days (default 14, clamp 2-30) and window (24hr | 1wk | 1mo, default 1wk). The tool description only repeats these defaults and ranges without adding new semantic context, so it adds minimal value beyond the schema.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and directly answers the question 'how long has this edge existed and is it shrinking?'. This specific verb+resource formulation distinguishes it from sibling tools like polymarket_edges and polymarket_arbitrage, which likely focus on current edges or arbitrage opportunities.

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

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

The description establishes a clear use case for analyzing edge persistence and decay over time, with examples ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly name alternatives or state when not to use this tool, only implying that it is built atop polymarket_edges snapshots.

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 readOnly, idempotent, and openWorld, but the description adds substantial behavioral detail: walks the order-book ladder, returns verdict clean|degraded|cannot_fill, identifies thin legs, and names forced directional risk. It also warns that partial basket fills convert an arb into an unhedged directional position. 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 front-loaded with the primary purpose and every sentence carries relevant detail. However, it is a single dense paragraph without line breaks or bullets, which reduces scannability. Some redundancy in the 'USE THIS' emphasis, though justifiable for safety-critical usage.

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 compensates by enumerating all key return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, per-leg fill details, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk). It covers both modes, input semantics, and risk interpretation—making it exceptionally complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: size_usd is clarified as 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode; side default behavior ('auto from partition sum') is explained; clamping range is disclosed. This enriches parameter understanding far 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 states the tool's specific function: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by focusing on fill risk and slippage rather than just edge detection or arbitrage signals.

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 provides usage gates: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to favor single-market vs basket mode and warns against partial basket fills, giving actionable decision 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 only indicate read-only, open-world, idempotent behavior. The description adds extensive transparency: two modes, response structure (leg prices, spread in pp), compatibility_warning triggers, temporal_alignment semantics, and skipped_cross_type/subtype counters. This goes far beyond annotation hints and contradicts nothing.

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

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

The description is long but front-loaded with core purpose and uses clear structural markers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence carries technical substance without filler, though it could be tightened by moving some implementation detail to later sections.

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

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

There is no output schema, so the description must explain return values. It does this thoroughly: leg prices, spread in pp, compatibility_warning cases, temporal_alignment, and skipped-cross counters. It also covers edge cases like non-equivalent bet shapes. For a complex read-only tool with zero required params, this is fully complete.

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

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

Schema coverage is 100% and already describes each parameter, so the baseline is 3. The description adds semantic value by explaining the two-mode interaction (topic vs explicit overrides) and the purpose of the pre-mapped list. This is helpful but partially duplicates schema descriptions of override behavior.

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

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

The description opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly specifying the tool's verb (compute spread) and resource (two named prediction markets). It distinguishes from siblings like polymarket_edges by explicitly targeting cross-venue analysis. The two-mode explanation further clarifies the tool's scope.

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

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

The description explains both usage modes (topic shortcuts vs explicit ticker/slug) and provides critical warnings about when the spread is not meaningful ('when they aren't the tool says so', 'pre-mapped ≠ tradeable'). It does not explicitly name alternative tools, but it gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds value by noting that it returns attribute rows (and geometry) and that the where clause is SQL-like. This goes beyond the schema and 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 compact, front-loaded with the purpose, and every sentence adds valuable operational detail. No fluff or redundancy. It balances specificity with brevity.

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

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

For a query tool with 6 parameters and no output schema, the description covers the return format, a usage pattern, and the source of the URL. It could mention pagination or error behavior, but these are not essential given the rich schema and 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 description doesn't need to repeat parameter definitions. It adds the actionable pattern using where='1=1' and out_fields='*' for sampling, which provides meaningful guidance beyond the schema's per-parameter descriptions.

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

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

The description clearly states the action ('Query') and the resource ('ArcGIS Feature Service / Map Service layer'), and specifies it uses a url from search_datasets. This distinguishes it from sibling tools like layer_info or search_datasets, making the 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 implies usage after search_datasets and provides a concrete sampling tip, giving clear context for when to use it. However, it does not explicitly mention when not to use it or name alternative tools, so it stops 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?

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is known. The description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the behavior of omitting the key to list all keys. No contradiction.

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

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

The description is three sentences, front-loaded with the main action, then usage context and scoping. Every sentence earns its place with no 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 tool with one optional parameter, no output schema, and strong annotations, the description fully covers purpose, usage, scoping, and sibling relationships. Nothing important is missing.

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

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

Schema description coverage is 100%, and the schema already explains that omitting the key lists all keys. The description repeats this and gives examples of key content, but adds no new parameter constraints or format details. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and also covers the list-all-keys mode. It explicitly references the remember tool, distinguishing it from the sibling forget and remember 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?

It provides concrete use cases ('the user's target ticker, an address, prior research notes') and explains the benefit ('without re-deriving it from scratch'). It also pairs with remember and forget, offering a workflow orientation. It does not explicitly state exclusions, 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?

Annotation contradiction: readOnlyHint=true while description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones' — a state-changing side effect. This directly contradicts the read-only annotation, so the description does not align 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?

Three sentences, no fluff, key actions and alternatives front-loaded. Efficient and readable.

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

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

Covers return fields, filtering, mark_read, and alternatives. Does not explicitly mention unread_only interaction or default limit, but those are in the schema. Lacks output schema but describes what events carry.

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

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

Schema covers all parameters with descriptions, but the description adds practical context: example type 'sec_8k', clarifies since as ISO timestamp, and explains mark_read's side effect on future calls. Does not mention limit or unread_only, but schema already covers those adequately.

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 'Pull fired events from your subscription feed,' which clearly states the verb (pull) and resource (subscription feed alerts). It distinguishes from siblings like recent_changes and list_subscriptions by focusing on fired alerts with specific return fields.

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

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

Provides clear usage context: polling is fine, filtering by type and since, mark_read behavior, and an alternative REST endpoint for scripts/dashboards. Does not explicitly say 'use this instead of X' but the context is strong enough to infer when this tool is appropriate.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses the parallel fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO sunset/soft-fail behavior, accepted `since` formats, and the return structure (changes[], total_changes, pipeworx:// URIs). This adds substantial behavioral context that annotations cannot convey.

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

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

The description is dense but well-organized: example queries first, then source details, parameter formats, return shape, and sibling comparison. Every sentence adds essential context, and the length is justified by the tool's multi-source complexity. No fluff or redundancy.

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

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

Despite having no output schema, the description explicitly states the return format (changes[] grouped by source, total_changes count, pipeworx:// URIs). It covers input formatting, source fallbacks, caveats (USPTO sunset), and the sibling distinction. This is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds value by providing concrete examples for `since` (ISO date or relative shorthand) and recommending '30d' or '1m' for typical monitoring. It also clarifies that `value` can be a ticker or CIK, reinforcing the schema. Since it enhances rather than just repeats, a 4 is appropriate over the 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 uses a specific verb phrase ('What's new with X' / 'change feed for a company') and clearly distinguishes itself from entity_profile by stating that entity_profile is for static profiles. It also provides multiple example queries, making the tool's purpose immediately understandable.

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

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

The description explicitly states when to use the tool (for temporal 'what's new' queries) and when to use an alternative ('Use entity_profile instead when you want the static profile... regardless of window'). It also details internal fallback behavior (GDELT→GNews, PatentsView soft-fail) and gives recommended `since` values ('30d' or '1m').

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 idempotentHint and non-read-only, but the description adds critical behavioral context: memory is scoped by identifier, authenticated users get persistent retention, anonymous sessions retain for 24 hours. This goes beyond annotations and informs the agent about data lifecycle.

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

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

The description is four sentences, each earning its place: main purpose, when to use, technical details (scoping/retention), and related tools. It is front-loaded with the core function and avoids fluff.

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

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

For a simple 2-parameter tool with no output schema, the description covers purpose, usage scenarios, persistence semantics, and relationships with sibling tools. It is fully sufficient for an agent to decide when and how to invoke it.

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

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

Schema has 100% coverage with descriptions for key and value, so the baseline is 3. The description doesn't add substantial parameter-specific semantics beyond what the schema provides, though it does contextualize key-value pairs with examples in the usage guidance.

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 saves data for reuse later, with a specific verb ('Save') and resource ('data'). It distinguishes itself from sibling tools by mentioning paired tools 'recall' and 'forget', making its role in the memory workflow explicit.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' and gives concrete examples (resolved ticker, target address, user preference). It also advises pairing with recall for retrieval and forget for deletion, effectively covering alternatives.

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

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

The annotation already provides readOnlyHint, idempotentHint, and destructiveHint, so the description doesn't need to restate safety. It adds valuable behavioral context by noting 'auto-disambiguated' inputs, internal cascading through multiple endpoints, and that it replaces 2-3 manual lookups—insights not covered by annotations or schema.

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

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

The description is front-loaded with the core purpose and examples, followed by organized type-specific details and a closing efficiency note. Every sentence adds value, and the formatting with quoted examples and SUPPORTED TYPES makes it scannable and clear.

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

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

Although there is no output schema, the description lists the key return fields and citation URIs for each type, providing enough detail for an agent to understand the result shape. It also covers supported inputs and the internal resolution process. It lacks error-handling or edge-case info, but given the tool's simple role, it is nearly 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 covers parameter descriptions well (100% coverage), but the description enhances the 'type' parameter by explaining what each enum value returns (e.g., company returns ticker + CIK + company_name, drug returns RxCUI). It also gives concrete input examples for 'value,' going beyond the schema's generic phrasing.

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: resolving user-spoken names to canonical/official identifiers. It provides concrete examples (ticker, CIK, RxCUI) and lists supported types with specific outputs, distinguishing it from siblings like entity_profile or compare_entities by emphasizing it's the prerequisite for other tools.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear directive on when to use this tool. It also includes example queries to illustrate the intended use case. However, it does not mention alternatives or when NOT to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/safe, so the bar is lower. The description adds useful behavior details: it probes each entity with ai_visibility_check, ranks results by score, and returns score/confidence/signal density. 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 compact and front-loaded: the primary action is in the first sentence, and every subsequent sentence adds distinct value (mechanism, use case, output). No filler or repetition of schema/annotation 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?

There is no output schema, but the description explicitly states the return format ('ranked list with score, confidence, signal density per entity') and covers the probing mechanism and entity roles. For a tool with moderate complexity and all parameters documented in the schema, this is complete enough.

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 meaning by explaining that the first entity is the 'subject' and the rest are competitors, which is not in the schema. It also clarifies the purpose of the context parameter. This extra semantic value justifies a 4.

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

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

The description opens with a specific action ('Compare AI visibility across multiple entities side-by-side') and clearly distinguishes itself from sibling tools by naming ai_visibility_check as the probing mechanism and by emphasizing the comparative, multi-entity scope. This is a specific verb+resource+scope that separates it from single-entity checkers and general compare tools.

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

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

The description gives a clear use case ('competitive AI-marketing audits') with an example query, and it implies the alternative (use ai_visibility_check for a single entity). However, it does not explicitly state when not to use this tool or name alternatives like compare_entities, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds valuable behavioral context: it fans out across multiple sources, degrades gracefully on partial failures, and notes that bundlephobia's first measurement can take 5-30s with sources_failed reporting timeouts. This goes beyond the annotations and describes failure modes and latency.

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

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

The description is longer than average but every sentence carries unique information: purpose, use cases, return block, ecosystem scope, and failure behavior. It is structured with a clear flow from what → when → what you get → edge cases. No filler or redundancy.

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

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

There is no output schema, so the description must explain return values. It does so comprehensively, listing the summary block fields, per-advisory details, links, and alternative versions. It also covers latency, error handling, and ecosystem limitations, making the tool fully understandable for an agent without missing context.

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

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

Schema description coverage is 100% for both parameters (package and version). The description does not add meaning beyond the schema—it mentions scoped packages and version default, both already in the schema. Baseline 3 is appropriate since the schema fully documents the parameters.

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

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

The description opens with a specific verb+resource: 'Composite "should I add this npm package to my project" check in ONE call'. It clearly distinguishes the tool from the broader research-oriented siblings (deep_research, bet_research) by naming the exact sources (deps.dev, bundlephobia) and the npm ecosystem scope.

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

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

Explicit usage guidance is given: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states ecosystem boundaries ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly') and warns about latency and partial failures, which helps agents decide when this tool is appropriate.

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

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

The annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context by disclosing the exact return fields (name, summary, record_count, owner/org, Feature Service url) and the intended follow-up usage, 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?

The description is two sentences and front-loaded: the first sentence states the action, resource, and scope, and the second specifies return values and next steps. Every word earns its place, with no repetition or filler.

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

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

Even without an output schema, the description fully explains what results look like (name, summary, record_count, owner/org, url) and how to use them. For a search/discovery tool, this is sufficient context to enable correct invocation and downstream chaining to query_layer or layer_info.

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

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

The input schema already provides 100% coverage with clear descriptions for all three parameters (query, limit, org_id). The description does add the context that 'keyword' refers to terms like parcels or zoning, and that results are Linn County GIS datasets, but this is marginal beyond the schema's own 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 ('Search') plus a clear resource ('Linn County GIS open geospatial datasets') and scope ('by keyword'). It also distinguishes this tool from sibling tools like query_layer and layer_info by explicitly stating it returns Feature Service URLs to be passed to those 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 clearly indicates when to use the tool: to find datasets by keyword. It also provides usage guidance by telling the agent to pass the returned url to query_layer or layer_info, which is a concrete downstream action. However, it does not explicitly state when not to use it or compare with alternative search tools like search_within.

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

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

Discloses detailed behaviors beyond the annotations: outputs include character offsets and similarity scores, uses BGE-base-en embeddings, cosine over 500-char overlapping windows, and a 200K char cap with truncation and flagging. This is valuable context for an 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 five tightly packed sentences, each earning its place: purpose, use case, pairing, and technical details. No filler or redundancy.

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

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

Despite the lack of an output schema, the description explains the return format (top-N passages with character offsets and similarity scores), truncation behavior, and the 200K character input limit, making it complete 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 descriptions cover all three parameters at 100%, so the baseline is 3. The description adds example texts and queries, but does not fundamentally extend the meaning of the parameters beyond what the schema already states.

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

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

The description clearly states the tool's function: 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from siblings by emphasizing 'a fetched record' and explicitly pairing with ask_pipeworx_grounded.

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt' and mentions an alternative/companion tool: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.'

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 critical execution constraints: requires a Pipeworx OAuth account, anonymous/BYO cannot persist, phone verification for SMS, and a 10/day SMS cap. It also states the feed is always on. These add meaningful context beyond the annotations' readOnly/idempotent/destructive hints.

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

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

The description is dense but well-structured, front-loading the core action and return value, then enumerating types and channels. While long, it stays on-topic with no filler.

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

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

It misses two supported types (patent_grant, clinical_trial) and the webhook delivery channel that appear in the schema. It also only says 'Returns the new subscription id' without mentioning the one-time webhook secret or broader response format, which is problematic given no output schema.

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

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

Although the schema already documents parameters (100% coverage), the description goes further by giving concrete examples for each supported type (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE'). It also explains delivery parameter constraints like phone verification and the 10/day cap, which are not fully detailed 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?

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' clearly identifying the verb, resource, and intention. This differentiates it from sibling tools like list_subscriptions and unsubscribe, which manage the lifecycle rather than create.

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 implies usage via 'proactive monitoring subscription' but does not explicitly state when to use vs alternatives. The only alternative mentioned is 'recent_alerts' for pulling the feed, which is a consumption option, not a contrast with other subscription-management 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, openWorldHint, idempotentHint, and destructiveHint false, covering safety. The description adds context beyond annotations: it returns category-bucketed example questions drawn from a live catalog of thousands of tools, and can be focused by topic. It does not disclose potential volatility of the live catalog or response size, but overall adds meaningful behavioral context.

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

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

The description is a single dense paragraph that is front-loaded with the main purpose and example queries. While it is long, every clause adds useful information (categories, output format, topic usage, when to use). It could be split into clearer sentences, but the content is efficient and earns its length.

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

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

With no output schema, the description fully explains what the tool returns: category-bucketed example questions with exact tool and argument shape. It covers the one parameter, provides usage guidance, and frames the tool within the broader meta-tool ecosystem. This is complete for a simple read-only tool with strong 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?

The schema already documents the optional `topic` parameter with enum values and the omit-for-full-spread behavior, providing 100% coverage. The description repeats this information with examples ('finance', 'pharma', 'betting') but adds no new semantic detail beyond what the schema provides. Thus 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 this is the onboarding entry point for an agent that just connected, with specific examples of queries it handles ('what can I ask Pipeworx?', 'what is Pipeworx good for?'). It distinguishes itself from siblings like discover_tools by emphasizing it returns category-bucketed example questions with exact tool and argument shapes, not just a tool list.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' giving clear when-to-use guidance. It also explains how to adjust the call (no arguments for full spread, pass topic to focus), but does not mention when-not-to-use or direct alternatives like discover_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 indicate a non-read-only, non-destructive, idempotent operation, but the description adds substantial context beyond that: ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible through recent_alerts. This fully discloses the real-world side effects without contradicting any annotation flags.

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, highly efficient, and front-loaded with the action. Every clause provides value, including the ownership constraint and the deactivation side effect. No redundant or filler content 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 simple one-parameter tool with no output schema, the description covers purpose, usage context, ownership rules, and the non-destructive side effect. It also explicitly points to the related tool (recent_alerts) for historical events, making the context complete. The annotations cover the safety profile, so no additional behavioral disclaimers are needed.

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

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

The schema covers the single parameter 'id' with 100% coverage, describing it as a subscription id returned by subscribe. The description adds minimal parameter-specific meaning beyond the schema, only reinforcing that the id must be your own through the ownership mention. Baseline of 3 is appropriate because the schema already carries the descriptive load.

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

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

The description opens with 'Cancel a subscription by id,' which is a specific verb plus resource and method. It clearly distinguishes from siblings like subscribe (creates), list_subscriptions (lists), and recent_alerts (historical events). The additional ownership enforcement detail further clarifies the scope.

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

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

The description implies when to use: when you need to cancel a specific subscription. It provides useful context by stating ownership is enforced and that deactivation preserves historical events via recent_alerts, which hints at an alternative tool for historical data. However, it does not explicitly list when not to use it or fully enumerate alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds substantial behavior detail: dual-path pipeline, verdict types, verbatim evidence with citations, and the fact that it replaces 4-6 sequential calls. This is far beyond what annotations provide and contains no contradictions.

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

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

The description is dense and front-loaded with examples, but it earns its length by covering purpose, routing, output, and value. It is slightly verbose with phrases like 'Replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison)' which are informative but not essential, making it very good but not perfectly concise.

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 2 parameters, no output schema, and moderate complexity, the description is fully complete. It specifies the return verdict types, the actual value with citation, reasoning, and the exact routing behavior, leaving no ambiguity about invocation or expected results.

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

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

Schema coverage is 100%, but the description adds meaning beyond schema descriptions. For tolerance_pct it explains the default (implied by wording, capped at 5) and gives concrete usage guidance ('set 1–2 for hallucination detection'), and for claim it provides real-world examples. This extra context significantly enriches parameter understanding.

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

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

The description opens with natural-language user examples and states 'natural-language claim verification against authoritative sources,' clearly identifying the tool's purpose. It distinguishes between the structured SEC EDGAR path for company-financial claims and the grounded pipeline for all other factual claims, differentiating it from sibling tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context. It explains routing rules for different claim types but does not name alternative tools or explicit exclusion cases, so it falls short of a 5.

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