Arcgis Lakeland

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond annotations by disclosing the default model (Workers AI Llama-3.3-70b, free), the BYO-key mechanism for Anthropic ('you pay Anthropic directly'), and the exact return structure (score, confidence, signals, raw_response, combined view). This adds practical behavioral and cost context without contradicting any annotation.

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, each earning its place: purpose, configuration/cost detail, return format and use cases. It is front-loaded with the core function and avoids redundant phrasing or repetition of schema field names. Efficient and well-structured for an agent to parse.

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 takes on the burden of explaining return values, which it does explicitly: 'per-model {score, confidence, signals, raw_response} + a combined view.' It also covers default behavior, optional configuration, cost implications, and typical usage scenarios. This is sufficiently complete for an agent to understand the tool's capabilities and decide invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by specifying the default model for the 'models' parameter and clarifying the financial implication of _apiKey ('BYO key — you pay Anthropic directly'). These are meaningful additions not present in the schema descriptions, justifying a 4.

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

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

The description opens with a specific verb+resource+output: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly defines the tool's function and distinguishes it from siblings like ask_pipeworx or scan_competitor_ai_presence by focusing on aggregated visibility scoring rather than answering a question or scanning a specific competitor.

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: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implicitly tells agents when to choose this tool. However, it does not explicitly name alternative tools or state when NOT to use it, so it stops short of the explicit exclusion guidance 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 establish read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable behavioral context: it returns structured answers with stable citation URIs, works on every tier, and makes a single fast call. There is no contradiction with annotations, and these additions help an agent anticipate the tool's behavior.

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

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

The description is long but impeccably structured: it starts with a bold directive, then enumerates supported domains, explains the mechanism, provides usage cues and examples, and ends with comparisons to alternatives. Every sentence adds distinct value, with no filler or redundancy. The formatting (capitalization, line breaks) further enhances readability.

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

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

For a complex routing tool with no output schema, the description covers essential context: what types of questions to ask, what kind of answer to expect (structured, with citations), and how it compares to sibling tools. It does not explain the exact response format or pagination, but that is not necessary for an agent to decide whether to invoke this tool.

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

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

The input schema already covers all parameters with descriptions, including aliases for 'question', so description coverage is 100%. The description does not add semantic detail about parameters beyond the schema, but it does provide illustrative examples that indirectly clarify usage. This matches the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: a default entry point that routes questions to thousands of tools across verified sources, and explicitly distinguishes it from siblings like ask_pipeworx_grounded and deep_research. It uses a strong, specific framing ('PREFER OVER WEB SEARCH') and provides concrete examples, making its functionality unmistakable.

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

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

The description provides explicit when-to-use guidance, covering triggers ('whenever the user asks "what is", "look up"...'), default behavior ('START HERE'), and clear alternatives for more specific needs ('Step up only when needed' for grounded or deep_research). It even addresses edge cases like breaking news, making it highly actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the description adds context beyond this: it is a full working router with no fallback, experimental routing improvements enabled live, and currently matches ask_pipeworx exactly. No contradiction with annotations.

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

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

The description is a bit longer than necessary but each sentence adds useful context. It could be tightened (e.g., repeating 'currently matches ask_pipeworx' twice), but it remains structured and front-loaded with the key beta distinction.

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

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

Given the tool's complexity (a router with 5,564 tools) and absence of output schema, the description sufficiently explains its experimental nature, current behavior, and relationship to the stable version. It covers all essential aspects 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?

Schema description coverage is 100% with all six parameters (question and aliases) described. The description adds no parameter-specific meaning beyond stating 'same arguments' as ask_pipeworx, so it relies on the schema's existing documentation.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,564 tools, arguments, and response shape. It distinguishes itself from stable ask_pipeworx by noting candidate routing improvements under test, so its purpose is specific and clear.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing,' providing clear when-to-use guidance. It also references the stable router and comparison process, but does not explicitly mention alternatives like ask_pipeworx_grounded or other 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?

The annotations already include readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so basic safety is covered. The description goes beyond by disclosing the refusal behavior with explicit refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and the return structure including evidence and confidence. It also discloses that it costs an extra LLM call, which is critical operational impact.

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: starts with a clear purpose, then explains behavior, return values, usage guidance, and cost trade-off in a dense but organized paragraph. Every sentence adds value—no filler or repetition. It fits within a few sentences and front-loads the key purpose.

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

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

For a read-only, idempotent tool with a single required parameter, the description is comprehensive: it explains the routing (picks from 5,564 tools), the extraction process, the refusal cases, and the return payload. There is no output schema, but the description details the return structure including refusal_reason values, making it complete for agents to understand expected outputs and failure modes.

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 coverage is 100%, and the description does not add much beyond what the schema already says: it mainly explains the 'question' parameter and lists aliases. The parameter semantics are fully documented in the schema, so the description adds minimal additional meaning, but no deduction is needed since coverage is high.

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 a 'hallucination-resistant answer mode' for high-stakes reads, distinguishing it from the sibling 'ask_pipeworx' by emphasizing extraction from tool results only. It specifies the verb (answer) and the resource (Pipeworx), and explicitly differentiates from a sibling tool by noting the extra LLM call cost.

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

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

It explicitly says 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and gives concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also states when NOT to use it: 'prefer ask_pipeworx for casual lookups' and mentions the cost trade-off, providing clear guidance on choosing between 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?

Adds extensive behavioral detail beyond the readOnly/idempotent annotations: fan-out logic, resolver contract, safety blocking statuses (low_confidence_match, market_closed_or_inactive), wide-spread warnings, and cancellation-rule parsing. No contradiction with annotations; the description and annotations align well.

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 extremely well-organized with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and a front-loaded purpose. Every section provides unique, valuable information that would be unavailable from structured fields; nothing feels like 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?

With no output schema, the description fully documents return shapes (result.market, result.analysis, result.evidence), the resolver contract, parent-event extraction, news retry fields, and blocking edge cases. It also covers resolution-rule risk, which is critical for sizing. No significant gaps remain 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 the schema descriptions are already rich (market formats, depth enum, include_raw tradeoffs). The tool description adds no new parameter-level semantics beyond re-emphasizing that market can be a slug, URL, or question text. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It also gives concrete example queries and distinguishes itself from sibling edge-scanning tools by focusing on a single market with a market-vs-model comparison.

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

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

Explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not name alternative tools or state when not to use it, so it misses the top score by a narrow margin.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral context: it pulls specific financial metrics from SEC EDGAR/XBRL, handles off-calendar fiscal years (e.g., AAPL Sep, NVDA Jan), sorts results by primary metric, returns paired data with citation URIs, and claims to replace 8–15 sequential lookups. This goes beyond what annotations or schema 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 dense and information-packed, but organized with concrete examples and a clear lead. Every sentence contributes either to purpose, usage, or behavioral detail. The only minor drawback is that the initial sentence lists many natural-language triggers, making it a bit longer than necessary, but it remains focused and scannable.

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

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

Despite having only two parameters and no output schema, the description fully covers what data to expect (financial metrics for companies, adverse-event counts for drugs), how results are presented (sorted by primary metric, paired data, citation URIs), and how this tool fits into the broader workflow (replaces many lookups). There are no significant missing pieces for an agent to invoke and interpret results.

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

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

Schema provides full descriptions and examples for both parameters (type enum, values min/max). The description enriches these by explaining exactly what each 'type' retrieves (10-K fields vs FAERS/FDA/trials) and elaborates on the 'values' format with specific examples like ["AAPL","MSFT"] and ["ozempic","mounjaro"]. It also clarifies how the primary metric determines sorting, adding meaning beyond the schema.

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

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

The description opens with concrete trigger phrases like 'Compare X and Y' and 'X vs Y', making the tool's purpose immediately clear. It explicitly states the resource (2–5 companies or drugs) and the action (side-by-side comparison), and distinguishes itself from siblings like 'entity_profile' by emphasizing parallel comparison vs. sequential lookups.

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

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

It provides explicit guidance with 'ALWAYS PREFER over sequential single-pack lookups', giving a clear when-to-use and what to avoid (sequential lookups). It also details type-specific use cases (company vs drug) and the exact entities they cover, which helps the agent choose correctly.

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

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

Annotations already convey read-only, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: account/tier requirements, parallel decomposition, gap reporting with explicit gaps[], contradiction detection for deeper depths, semantic excerpting, resolvable citation_uri behavior, and expected latency. No contradiction with annotations is present.

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 the most critical operational constraint (account/sign-in) and dense with necessary behavioral specifics. Every sentence carries useful information, though the length is substantial; for a tool this complex, the structure is reasonable rather than wasteful.

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

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

Given the tool's complexity, no output schema, and two influential parameters, the description is remarkably complete: it explains output packet contents, gaps, contradictions, citation resolvability, hop semantics, timing, and source catalog limits. It leaves very little for an agent to guess, and the sibling-tool differentiation is thoroughly handled.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds beyond the schema by explaining how 'question' benefits from being broad/multi-part ('decomposition is the point') and by enriching depth semantics with behavior differences (gap recovery, lead chasing, contradictions scan). This is meaningful added value, though not dramatically above the detailed schema.

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

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

The description uses a specific verb + resource: 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' with concrete examples of use cases. It clearly distinguishes itself from sibling tools like ask_pipeworx by stating this is NOT open-web search and by positioning it as the tool for broad/multi-part structured-data questions.

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

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

The description gives explicit when-to-use guidance: use for broad/multi-part structured-data questions, use ask_pipeworx for single lookups, and prefer ask_pipeworx for breaking/current-news topics. It also names an alternative for unsigned-in users and explains the paid-tier requirement for 'thorough', making routing decisions 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that, such as returning top-N results with names, descriptions, and full schemas 'ready to call directly, no second schema lookup needed.' It does not contradict 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, followed by usage context and a domain list. It is somewhat lengthy due to the enumeration of domains, but each part serves a function: the domain list aids query formulation and the return-behavior sentence justifies calling the 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?

Given the tool's simple one-required-parameter nature, the description is complete. It explains what the tool does, when to use it, and what it returns (names, descriptions, schemas with examples), covering the key aspects an agent needs 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?

Input schema has 100% coverage, documenting the query parameter and its aliases, plus a limit parameter with defaults and max. The description's mention of 'describing the data or task' and the domain list helps formulate a query, but it does not add new parameter details 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?

Description begins with 'Find tools by describing the data or task,' a specific verb+resource that directly states what the tool does. It further clarifies by listing concrete domains and highlighting that it returns tool names, descriptions, and schemas, which clearly distinguishes it from sibling data-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 explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and advises 'Call this FIRST when you have many tools available.' This provides clear when-to-use guidance, though it does not name alternative tools or state explicit when-not-to-use conditions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields, mentions that the USPTO API is sunset with soft-fail, and describes a GDELT→GNews fallback. 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 well-structured. It opens with user-intent examples, then states the core function, then lists return fields, then covers limitations. Each sentence adds information; however, the parameter and limitation details are interleaved, which slightly hurts readability. Still, it remains efficient overall.

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

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

Without an output schema, the description fully explains return values (cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI). It also covers edge cases like unsupported name input and source fallback behavior. For a tool with this complexity, the description is remarkably complete.

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

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

The input schema already documents type and value with 100% coverage. The description reinforces this by providing concrete examples ('AAPL', '0000320193') and reiterates the name limitation, which adds practical clarity beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It gives specific example queries ('Tell me about X', 'company profile for Microsoft') and explicitly differentiates from chaining single-pack lookups, making its 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?

The description explicitly states when to use it: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent when not to use it: names are not supported, and instructs to 'use resolve_entity first if you only have a name.' This provides clear decision 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=true and idempotentHint=true, covering the safety profile. The description adds the context of why to use it (clearing sensitive data) but doesn't disclose additional behavioral aspects like permanence or error handling, though these are implied by the annotations. 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 short sentences, front-loaded with the core action first, then usage context. Every sentence adds value.

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

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

For a single-parameter delete tool with strong annotations, the description covers purpose, usage context, and relation to siblings. It doesn't describe return behavior or non-existent key handling, but given the simplicity and annotation coverage, it is sufficiently 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 single parameter 'key' is fully described in the schema with an example. The description merely says 'by key', adding no new semantic information beyond the schema.

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

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

The description uses the specific verb 'Delete' and the resource 'previously stored memory by key', clearly distinguishing it from siblings like remember and recall. It is unambiguous and actionable.

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 three trigger conditions (stale context, task done, sensitive data) and instructs pairing with remember and recall, providing clear guidance on 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 description discloses the process (fetches page, extracts title/description/key links, emits markdown) and the output format (single text blob for site-root/llms.txt), adding valuable context beyond the annotations. Given the annotations already convey safety (readOnly, idempotent, non-destructive), this level of transparency is sufficient.

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

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

The description is three sentences, front-loaded with the main purpose, followed by a brief process summary and actionable use cases. Every sentence earns its place, with 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?

The tool is simple (2 params, no output schema), but the description compensates well by explaining what the output looks like and the workflow. It does not cover edge cases like network failures or rate limits, but given the low complexity and strong annotations, this is a minor gap.

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

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

The input schema has 100% coverage for both parameters, so the baseline is 3. The description adds minimal parameter-specific meaning; it mentions 'any URL' aligning with the url parameter but does not elaborate on max_links. The schema handles parameter semantics 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 clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb and resource. This distinctly separates it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on checking AI presence rather than generating an index file.

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 useful scenarios (getting a client's site indexed, drafting llms.txt, auditing a competitor) which provides clear context for when to use the tool. It does not explicitly name alternatives or exclusions, but the use cases are specific enough to guide an agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is covered. The description adds context about return contents ('total record count' and 'capabilities'), which goes slightly beyond annotations but does not disclose potential rate limits, authentication requirements, or response behavior. With annotations present, this is adequate but not rich.

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

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

The description is a single, well-structured sentence that front-loads the verb and resource, then lists the specific return items. Every word contributes value; there is no filler or repetition. It is appropriately sized for the tool's simplicity.

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 one simple parameter and no output schema, the description fully enumerates the return values (fields, geometry type, record count, capabilities), providing enough context for an agent to know what to expect. No additional details about return formatting are necessary since the description covers the core output.

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 for the single 'url' parameter, including an example and description. The description's phrase 'by url' is redundant with the schema. It does add meaning by clarifying the URL identifies a layer and by listing the returned fields, but this is not parameter-specific. Baseline of 3 is appropriate given the schema's completeness.

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

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

The description clearly states a specific verb ('Get') and resource ('ArcGIS Feature/Map Service layer's schema'), and lists exactly what the tool returns: fields (name + type), geometry type, total record count, and capabilities. This is specific and distinguishes it from sibling tools like query_layer, which likely fetches data rather than schema.

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

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

The description implies usage: when you need schema information for an ArcGIS layer, use this tool. However, it does not explicitly mention alternatives or provide exclusions, such as 'for querying features, use query_layer instead.' The context is clear but lacks explicit comparative guidance.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds that the response is scoped to the caller ('caller's active subscriptions') and lists the exact fields returned, which goes beyond annotation. No contradiction exists.

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

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

Two sentences, front-loaded with the action and return payload, no unnecessary words. Every sentence adds value, and the structure is easy to scan.

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

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

For a simple list tool with one optional parameter, strong annotations, and no output schema, this is complete. It explains the return shape, the default scope (active), and the practical use cases. Nothing essential is missing.

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

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

The schema has 100% coverage for the single optional parameter include_inactive, with a clear description and default. The tool description adds 'active' context indirectly, but does not need to re-explain the parameter since the schema fully covers it.

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

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

The description uses a specific verb+resource: 'List the caller's active subscriptions.' It clearly distinguishes from sibling tools like subscribe/unsubscribe by focusing on read-only listing. It also enumerates the return fields, leaving no ambiguity about what the tool does.

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

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

The description explicitly states when to use it: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly contrasts with subscribe and unsubscribe tools, giving the agent clear 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?

With all annotation hints false, the description carries the full transparency burden. It discloses the claim_token workflow, rate limit of 5 per identifier per day, quota exemption, and the fact that feedback is read in daily digests. These details go well beyond the annotations and there is 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 long but every sentence earns its place: purpose, usage categories, scope restriction, message guidance, claim-token workflow, roadmap impact, and operational limits. It is front-loaded with the core purpose and then layers necessary constraints and follow-up behavior without redundancy.

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

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

The description covers scope, message content guidelines, claim-token follow-up, rate limits, quota impact, and review cadence. It is slightly ambiguous about return behavior when an account is present versus anonymous filing, and there is no output schema to fill that gap, but the core invocation and follow-up flow are clear.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds useful semantic context by explaining that the message should reference Pipeworx tools/packs, demonstrating the claim_token invocation pattern, and clarifying that claim_token usage with no other arguments retrieves resolution status. It does not add meaning for the context object beyond the schema, but the existing schema is strong.

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+resource: telling the Pipeworx team about broken, missing, or desired capabilities. It further scopes the tool to this Pipeworx connection and explicitly distinguishes it from feedback for other MCP servers, so its purpose is unambiguous and distinct.

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

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

The description gives explicit categories for when to use it (bug, feature, data_gap, praise) and a clear exclusion: if the issue belongs to a different MCP server, file it there instead. It also gives practical guidance like not pasting the end-user's prompt, making usage conditions concrete.

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

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

Beyond the read-only/idempotent annotations, the description discloses that results are self-aggregating, derived from CF analytics-engine, contain no PII, and are cached for 5min-1h. This adds valuable context about data provenance and freshness, but stops short of explaining exact output structure or pagination.

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

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

The description is longer than a single sentence but well-structured: a summary sentence, a bulleted list of use cases, and a concise data-provenance note. Each sentence adds value, with 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?

With no output schema, the description compensates by explicitly mentioning return contents (top tools, packs, call volume), data origin, and caching. Combined with the three use cases, this fully equips an agent to understand 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%, and the schema already explains the window parameter's enum values and semantics (short windows for hot trends, longer for steady-state). The tool description only repeats the window options without adding new meaning, so it meets the baseline but does not exceed it.

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

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

The description clearly states what the tool returns: top tools, top packs, and total call volume for a recent window. The phrase "what other AI agents are calling on Pipeworx right now" conveys the specific purpose and distinguishes it from siblings like discover_tools by focusing on trending/aggregate usage.

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

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

The description provides three explicit use cases (identifying hot data sources, confirming canonical tool choices, and checking alignment with agent demand), which is clear guidance. However, it does not mention when not to use the tool or alternative tools, so it earns a 4 rather than 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?

Beyond the read-only annotation, it details internal validation steps: threshold for partition deviation >3pp, Jaccard similarity >=0.30, placeholder filter >20%, and the fill check against live CLOB depth. It also discloses that a realizable edge <=0 means the opportunity is not tradable, which is critical 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?

Though long, the description is carefully structured: core purpose first, then the three call modes, then validation filters, response format, and fill-check caveats. Every sentence carries specific operational detail, with no filler or redundancy.

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

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

For a complex tool with no output schema and many modes, this description covers all essential aspects: the parameters, response fields (opportunities[], partition_check{}), edge cases like placeholder filtering, and integration with polymarket_fill_risk. It is complete enough for an agent to invoke correctly without further documentation.

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

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

The description greatly enriches the schema by giving actual slug examples ('fed-decision-may-2026') and noting full URLs are accepted for `event`. It explains the semantic difference between `event` (single-event scan) and `topic` (cross-event scan) and mentions the no-arg default, none of which are 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 specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' which clearly distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk. It also describes three distinct usage modes (default, event, topic), further clarifying its purpose.

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

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

It explicitly explains when to use each mode: 'Call with NO args for a trending_scan,' 'pass event for...' and 'pass topic for...' with concrete examples. It also provides an alternative: 'For custom sizing use polymarket_fill_risk,' and a clear when-not-to-trade condition: 'realizable_edge_pp ≤ 0 means... do not trade it.'

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds rich behavioral detail: 1h KV-level caching keyed on knobs, per-leg Kelly cap at 0.25, diagnostics for empty segments, and the 24h-move warning. It also discloses that the concentrated_longshot segment is 'rare-by-design' and Fed bets are excluded. No contradiction found.

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: introduction, model families, knobs, response top-level, diagnostics, and caching. It is front-loaded with the core purpose. Each section adds operational knowledge, though some technical density could be trimmed.

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

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

Given the tool's complexity and lack of an output schema, the description thoroughly covers return fields (edge_pp_net, kelly_fraction, market.liquidity, spread_pp, volume), response top-level structure (by_segment, fed_candidates, _diagnostics), and model-family behavior. This is sufficient for an agent to invoke and parse results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description groups knobs into 'TRADEABLE-EDGE KNOBS' and explains their purpose (e.g., 'drop opportunities where edge isn't realizable'), but it doesn't add syntax or format details 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 a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The 'Built for what should I bet on today' phrase positions it as a discovery tool, clearly distinguishing it from siblings like polymarket_arbitrage or 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?

It provides clear usage context: 'Built for what should I bet on today' and explains how the knobs adjust tradeable edge. It does not explicitly name alternative tools for different use cases, but it implies when this tool should be chosen over paging hundreds of markets.

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

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

Annotations already declare readOnly/idempotent, and the description adds substantial context: 60-day snapshot TTL, history depth starting when snapshotting was enabled, snapshots written only on cache-miss (explaining gaps), and decay computed from daily closes rather than intraday. This gives the agent critical behavioral 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?

The description is well-structured with the core purpose front-loaded, followed by args, response, and limits. It is dense and informative, but slightly verbose with illustrative comments like 'the latter is wide for a reason nobody is willing to take' that are not strictly necessary. Still, every section 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?

Without an output schema, the description thoroughly defines the return structure (tracked, expired, snapshot_dates) including key fields like edge_pp_net time-series, trend, decay_pp_per_day, and lifespan_days. It also explains data availability constraints and computational basis, making it fully self-contained for the 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 description coverage is 100%, and the description adds no new meaning beyond the schema. 'days' and 'window' are fully described in the schema (lookback, default, clamp, enum values). The phrase 'snapshot family' is essentially synonymous with the schema's 'window family', so the description adds only marginal semantic value.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry built from daily polymarket_edges snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical telemetry rather than current edge discovery.

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

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

The description implies the use case by answering a specific question and explaining the data source (daily snapshots). It mentions relationship to polymarket_edges and snapshot gaps, giving clear context. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already establish safety, but the description adds substantial behavioral detail: it walks the order-book ladder, returns specific fields (slippage_pp, max_fillable_usd, verdict), and for basket mode exposes per-leg fill detail and 'forced_directional_risk'—explaining what outcomes to expect. No contradictions with annotations.

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

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

The description is long, but it is well-organized with labeled sections (SINGLE-MARKET, BASKET) and each sentence carries useful information. It could be slightly more succinct, but given the two-mode complexity, the length is justified and front-loaded with the core purpose.

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

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

Despite lacking an output schema, the description enumerates all returned fields in both modes, covers parameter defaults and clamps, explains the required market/event mutual exclusivity, and warns about the dominant failure mode. For a tool of this complexity, it is remarkably complete.

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

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

Even though schema coverage is 100%, the description enriches each parameter: size_usd is clarified as 'max spend on buys, target proceeds on sells' and in basket mode as 'settlement notional'; side gets a default and auto-selection logic; market and event are tied to modes. This goes far beyond the schema's bare definitions.

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

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

The description opens with a specific, action-oriented purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly differentiates two modes (single-market and basket) and explicitly contrasts itself with sibling tools like polymarket_arbitrage and polymarket_edges, making its unique function 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?

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable, partial basket fills create unhedged directional risk), giving clear 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description goes far beyond these by detailing the response structure (leg-by-leg prices, matched spread, top_spreads_pp), the compatibility_warning logic with two distinct cases, temporal_alignment semantics, and skipped_cross_type/subtype counters. It even discloses that most pre-mapped topics will return compatibility_warning, which is a non-obvious behavioral trait. 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 substantial but well-organized: it opens with a one-sentence definition, then breaks down modes, response fields, safety warnings, and a concluding caveat. Every sentence carries meaningful information, though a few clauses are densely packed (e.g., the compatibility_warning explanation could be parsed into simpler bullets). It is front-loaded and structured, and the length is justified by the tool's complexity, but it could be slightly tighter.

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 takes on full responsibility for explaining return values, and it does so thoroughly: leg-by-leg prices, matched spread[], compatibility_warning conditions, temporal_alignment fields, and skipped counters. It also explains the meaning of edge cases (e.g., matched_pairs:0 with skipped_cross_type>0) and why temporal misalignment invalidates spreads. For a tool with this many behavioral nuances, the description is remarkably complete.

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

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

The input schema already provides 100% coverage with descriptions for all three parameters, so the baseline is 3. The description adds extra semantic value by explaining the pre-mapped topic list in context, clarifying that explicit tickers 'override' the mapped side, and giving concrete examples for each parameter. This goes beyond simple schema repetition and helps the agent understand the mode relationship between topic and explicit overrides.

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 definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the exact resources (Kalshi, Polymarket) and the scope (spread comparison), and distinguishes it from sibling tools like polymarket_arbitrage by focusing on the cross-venue comparison aspect. It also outlines two distinct modes of operation, making the tool's purpose unambiguous.

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

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

The description provides explicit usage context by explaining the two modes ('topic' vs explicit tickers) and when each is appropriate. It also gives behavioral guidance like 'Real cross-venue spreads are rarer than the macro-shortcut list suggests' and 'pre-mapped ≠ tradeable,' which helps set expectations. However, it does not explicitly name alternative tools or state 'use this instead of X,' so it falls short of an explicit when/when-not set of alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the return content: 'Returns attribute rows (and geometry)' and provides a sample usage pattern, complementing the annotation-provided safety profile without contradiction.

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

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

The description is three short sentences, front-loaded with the main action, and every sentence contributes: purpose/source, parameters, return type and usage tip. No redundant phrasing 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?

For a 6-parameter query tool with no output schema and good annotations, the description covers essentials: what it queries, how to obtain the URL, key parameters, return type (rows and geometry), and a practical usage pattern. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description enhances parameter understanding by labeling `where` as 'SQL-like', and the tip 'where="1=1" + out_fields="*"' illustrates a common pattern for sampling all data, adding meaning beyond the schema.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Query an ArcGIS Feature Service / Map Service layer by its url'. It also references 'from search_datasets', distinguishing it from sibling tools like search_datasets (for finding datasets) and layer_info (for metadata). The purpose is unambiguous and well-differentiated.

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

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

The description provides clear usage context by indicating the URL originates from search_datasets, and offers a practical sampling tip: 'Use where="1=1" + out_fields="*" to sample.' It does not explicitly name alternative tools or state when not to use this tool, but the guidance is sufficient for typical use.

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

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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds valuable context beyond that: scoping to a user identifier (anonymous IP, BYO key hash, account ID) and the behavior of listing all keys when the key argument is omitted. This extra behavioral detail helps the agent understand side effects and privacy boundaries.

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 extremely concise at three short sentences, with the primary action front-loaded in the first sentence. Every sentence adds distinct value: functionality, usage context, sibling pairing, and scoping. No redundant words 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?

For a simple one-parameter tool with no output schema, the description sufficiently covers the core behaviors: retrieval, listing, scoping, and differentiation from related tools. It does not describe the exact return format or error handling, but those are not necessary for this simple read-only memory access tool. The annotations cover its safety profile, so the description 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?

The schema already documents the single parameter fully (100% coverage), so the baseline is 3. The description adds meaningful semantic enrichment by giving concrete examples of valid keys and emphasizing the omit-key behavior, which supports the agent's understanding of both parameter usage and output behavior.

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

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

The description opens with a precise verb ('Retrieve a value previously saved via remember') and clearly differentiates its two modes (retrieve specific key or list all keys). It also distinguishes itself from sibling tools by explicitly pairing with 'remember' and 'forget', making its purpose unambiguous and easy to select correctly.

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 when-to-use guidance with concrete examples (user's target ticker, address, prior research notes) and explicitly states how it fits with siblings: 'Pair with remember to save, forget to delete.' This equips the agent with both positive usage context and an alternative/replacement relationship.

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, but the description says mark_read:true flags returned events read so the next call only shows newer ones — a persistent state mutation. This directly contradicts the read-only annotation, which is a serious inconsistency.

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

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

Five sentences, front-loaded with purpose, then return format, filters, side-effect, and an alternative access path. Every sentence earns its place; 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?

Given no output schema, the description usefully lists return fields (source, citation_uri, raw payload) and explains filtering, mark_read behavior, and polling suitability. Minor gap: unread_only isn't described in prose, but the schema covers it, and there's no pagination caveat beyond the limit parameter.

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

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

Schema covers all 5 parameters (100%), so baseline is 3. The description adds meaningful semantics: type example 'sec_8k', ISO timestamp format for since, and mark_read's effect on subsequent calls. It doesn't mention unread_only in prose, but the schema already documents it.

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

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

Opens with 'Pull fired events from your subscription feed' — a specific verb and resource. It clearly identifies the tool's role (returning recent alerts from a persisted evaluator feed) and distinguishes it from siblings like recent_changes or list_subscriptions.

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

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

Provides clear usage context: filtering by type and since, setting mark_read, and mentions that polling works fine. It also names an alternative HTTP endpoint for scripts/dashboards, but doesn't explicitly contrast with sibling tools or state when not to use.

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 behavior, but the description adds rich context: parallel fan-out to multiple sources, rate-limit fallback, date parsing rules, soft-failure for patents, and the return shape with citation URIs. This goes well beyond the annotations.

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

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

The description is dense but each sentence carries unique information, starting with user intents, then mechanism, parameter details, return value, and alternative. It is slightly long but not padded; a strong structure earns a high score.

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

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

No output schema exists, but the description specifies the output structure (changes[], total_changes, citation URIs), covers failure modes and fallbacks, and contrasts with entity_profile. This is complete for a multi-source change-feed 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%, yet the description adds meaningful examples for `since` (ISO/relative formats, recommended '30d'), explains `value` as ticker or CIK, and notes `type` only supports company. This guidance aids correct invocation 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 provides a change feed for a company over a time window, with specific examples of user intents. It explicitly names the data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from the sibling entity_profile tool.

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

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

It gives concrete example queries ('What's new with X', 'updates on Acme') and explicitly directs users to entity_profile when a static profile is desired. It also explains fallback behavior between GDELT and GNews, plus the patent soft-fail, framing 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 description adds behavioral details beyond annotations: persistence across sessions, 24-hour retention for anonymous sessions, and scoping by identifier. It also clarifies that authenticated users get persistent memory, which is critical for understanding long-term side effects.

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 action, followed by usage context, storage semantics, and related tools. Every sentence earns its place without fluff, making it concise and well-structured.

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

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

With only two simple parameters and no output schema, the description fully covers the tool's lifecycle and behavior. It explains what data to store, why, when, and how it interacts with recall/forget, leaving no critical ambiguity for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces parameter meaning with examples ('a resolved ticker, a target address, a user preference, a research subject') and explains the key-value pair scoping, adding 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: 'Save data the agent will need to reuse later'. It identifies the resource (key-value store) and distinguishes itself from siblings by mentioning recall and forget, 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?

Explicit guidance is provided: 'Use when you discover something worth carrying forward...' followed by concrete examples. It also gives complementary tools ('Pair with recall to retrieve later, forget to delete'), clarifying when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds concrete behavioral traits: graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), internal cascading lookups, and explicit handling of unresolved identifiers under an 'unresolved' field. This adds value beyond annotations with no contradictions.

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

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

The description is front-loaded with example queries and purpose, then details supported types. Every section adds value. However, the block on company identity is verbose (multiple sources, labeling, graceful degradation interwoven). Some of this could be split into separate sentences or condensed without losing meaning, making it slightly less concise than ideal.

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

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

Given no output schema, the description covers return structure (identifiers labelled by source, unresolved listed explicitly) and graceful degradation. It explains both entity types thoroughly. The drug type output (RxCUI + ingredient + brand + citation) is mentioned but the overall return format is assumed (structured JSON). A brief explicit statement of the output shape would elevate completeness to a 5.

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

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

Schema coverage is 100% (baseline 3). The description adds practical examples for the 'value' parameter: 'ticker (AAPL), CIK (0000320193), or name' for company, and 'brand or generic name (e.g., "ozempic", "metformin")' for drug. It also enriches the 'type' enum by explaining what each type returns (e.g., 'cross-source identity spine' for company). This exceeds the baseline.

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

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

The description opens with concrete example queries (ticker, CIK, LEI, RxCUI) and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It explicitly says 'Use FIRST whenever you have a name but need an ID.' The detail on supported types (company, drug) clearly differentiates from sibling tools like entity_profile or compare_entities, which operate on already-resolved IDs.

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

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

The description provides strong positive guidance: 'Use FIRST whenever you have a name but need an ID' and lists the exact questions it answers (e.g., 'what's the ticker…?', 'who owns X'). It implies this tool is a prerequisite for tools that require IDs. However, it does not explicitly state when to avoid it (e.g., 'If you already have an ID, use entity_profile instead'), which would make the guidance complete.

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 that it internally calls ai_visibility_check for each entity, ranks results, and returns a specific structure (score, confidence, signal density). These behaviors go beyond the annotations (readOnly, idempotent, non-destructive) and give the agent a clear picture of what the tool does, including its internal composition and output.

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

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

The description is three sentences that front-load the core purpose, explain the mechanism, provide a use case, and summarize output. Every sentence adds value, and the structure is clear and scannable. No wasted words.

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

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

For a tool with moderate complexity (4 params, no output schema), the description covers the key aspects: what it does, how it works, when to use it, and what it returns. The output format is described sufficiently ('ranked list with score, confidence, signal density'), and the annotations cover safety. No critical gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema: it mentions 'your brand + N competitors' which mirrors the entities parameter description already provided. No extra parameter-level detail is added, so the score remains at the adequate baseline.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), the resource (AI visibility), and differentiates it from the sibling ai_visibility_check by focusing on multi-entity comparison and ranking. The example use case further clarifies the intended function.

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

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

The description provides clear context for when to use this tool: 'Useful for competitive AI-marketing audits' and gives a concrete example. It implicitly differentiates it from the single-entity tool by stating it probes with ai_visibility_check, which suggests the sibling for individual checks, though it doesn't explicitly state exclusions. This is strong guidance without fully spelling out 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 readOnly and idempotent behavior, but the description adds crucial operational context: partial failures degrade gracefully, bundlephobia's first measurement may take 5-30s, and sources_failed will list timeouts. This is beyond annotation scope and helps the agent anticipate real-world latency and error handling.

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, followed by usage, return summary, ecosystem scope, and failure behavior. Every sentence provides distinct, actionable information; despite length, there is no redundancy or filler.

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

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

With no output schema, the description enumerates the return summary fields (is_latest, license, etc.), per-advisory details, links, and alternative versions, plus failure handling. It fully covers the tool's behavior and data output, making it self-sufficient for an agent.

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

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

Schema coverage is 100% with clear descriptions for package (with scoped package mention) and version (with default behavior). The description adds contextual framing ('should I add this npm package') but does not introduce new parameter semantics, meriting the baseline score.

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 specifies a composite check for 'should I add this npm package to my project', naming the concrete resources (deps.dev and bundlephobia) and the specific fields checked. It distinguishes itself from sibling tools by detailing the fan-out to two data sources, making it uniquely identifiable.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also contrasts with alternatives by noting 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear exclusion 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by enumerating the returned fields (name, summary, record_count, owner/org, Feature Service url) and the next-step integration. 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 two sentences and front-loaded with the core purpose, then a compact summary of the return value and chaining. Every word adds value; no filler or repetition of structured fields.

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?

Though there is no output schema, the description lists the return fields and explains how the result (url) connects to sibling tools. It is complete for a read-only search tool; minor gaps like pagination or behavior when no results are found are not critical given the tool's simplicity.

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%; every parameter (query, limit, org_id) has a clear description in the schema. The tool description does not materially add parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb, resource, and scope: 'Search City of Lakeland GIS open geospatial datasets (parcels, zoning, utilities & city services) by keyword.' It also differentiates from siblings by explicitly describing the output and its role as a precursor to query_layer / layer_info.

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

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

The description provides clear context: this is for discovering geospatial datasets, and it includes the downstream workflow 'pass that url to query_layer / layer_info.' However, it does not explicitly state when not to use it or name alternatives, so it falls short of a 5.

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

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

The description discloses substantial behavioral details beyond the annotations: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging, and output containing offsets for verifiability. This adds significant context while not contradicting the readOnly/idempotent hints.

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

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

The description is front-loaded with purpose, then usage, then technical details. Every sentence contributes useful information—no filler or redundancy. The length is justified by the tool's complexity and the lack of an 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?

Despite having no output schema, the description fully explains the return structure (passages with offsets and similarity scores), edge cases (truncation flag), and an example pairing with another tool. Combined with the rich annotations and complete parameter schema, the agent has everything needed 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 100% description coverage with examples, defaults, and ranges. The description adds no new parameter-specific meaning—it merely restates 'top-N' and the character cap. 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 performs semantic search inside a provided text, with concrete examples of the input (SEC 10-K, article, long tool result) and the output (top-N passages with offsets and similarity scores). It also distinguishes itself from related tools by naming its pairing with ask_pipeworx_grounded and specifying the 'too big to cram into the prompt' use case.

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

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

Explicitly tells the agent when to use this tool ('Use when the record is too big to cram into the prompt') and provides a clear alternative/next step ('Pairs with ask_pipeworx_grounded'), giving actionable context for tool selection.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, etc.), the description discloses several behavioral traits: the need for OAuth, subscription ID return, sms verification and 10/day cap, webhook HMAC signing, and auto-disable after 10 failing runs. This adds significant context about side effects and constraints not present in the annotations.

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

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

The description is a single dense paragraph with all key information, but it could benefit from bullet points or section breaks for readability. Each sentence provides relevant detail, so it is appropriately sized for the tool's complexity.

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

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

For a tool with 3 parameters and nested objects, the description covers purpose, auth, types, and delivery channels. The schema covers the remaining parameter details, and the description states the return value (subscription ID), though it could elaborate on the full response format. Overall, it's 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% with detailed descriptions for type, params, and delivery. The description supplements this by giving concrete examples (e.g., items:['5.02'] = officer change, topic:'fed') that clarify parameter semantics, adding interpretive value beyond the raw schema.

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

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

The description uses a specific verb ('Create') and clearly identifies the resource ('a proactive monitoring subscription to a live-data event stream'), which distinguishes it from siblings like unsubscribe and list_subscriptions. The title 'Subscribe to Alerts' reinforces the action.

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

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

It provides clear context on when to use the tool (for proactive monitoring) and prerequisites (requires a Pipeworx OAuth account; anonymous/BYO cannot persist). It also explains delivery alternatives (feed vs email vs sms) within the tool, but does not explicitly contrast with sibling tools for one-time queries.

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 return behavior beyond the annotations: it returns category-bucketed example questions, each with the exact tool and argument shape, drawn from the live catalog. It also explains the no-argument vs focused-topic behavior. This significantly enriches the readOnlyHint/idempotentHint annotations by clarifying what the tool produces and how it behaves.

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 well-structured: it front-loads example phrasings, then explains the return payload, then parameter usage, then when to use. Every sentence contributes substantive information. It is longer than ideal but the length is justified for an onboarding tool that needs to orient a new agent.

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 an onboarding entry point with one optional parameter and no output schema, the description is complete: it covers what the tool returns, how to invoke it with and without arguments, the range of topics, and its relationship to meta-tools. No important aspect of the tool's behavior is left unexplained.

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

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

The schema already provides 100% coverage of the single `topic` parameter with a clear description. The description adds value by giving concrete examples ('finance', 'pharma', 'betting') and explicitly stating that omitting the parameter returns a cross-category spread. This clarifies usage beyond the schema's formal value list without being redundant.

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 multiple user phrasings ('What can I ask Pipeworx?', 'what are you good for?') and immediately establishes the tool as the onboarding entry point for discovering what Pipeworx can do. It clearly distinguishes itself from siblings by stating it returns example questions with the exact tool and argument shape, and by naming meta-tools (ask_pipeworx, entity_profile) that it teaches. The verb 'suggest' plus 'onboarding entry point' is specific and unambiguous.

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

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

Explicit usage guidance is given: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit the topic parameter versus passing a topic, and provides example values. This is clear, actionable, and helps the agent decide when to invoke this tool over alternatives.

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

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

The description goes beyond annotations by explaining the deactivation behavior ('row is deactivated (not deleted)') and its impact on historical events via recent_alerts. This adds useful context that the annotations (destructiveHint: false, idempotentHint: true) do not fully capture. Ownership enforcement is also a disclosed behavioral trait.

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

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

The description is two sentences, front-loaded with the primary action, and every sentence adds value. No filler or redundant information; it is concise and well-structured.

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

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

Given the simple tool (one parameter, no output schema) and helpful annotations, the description covers ownership rules, deactivation semantics, and links to related functionality (recent_alerts). It does not describe return values, but for a cancel operation this is not critical. The description is sufficiently complete for the tool's complexity.

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

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

The input schema already provides full parameter coverage (100%) including a clear description of the 'id' parameter. The main description's phrase 'by id' adds no further semantic meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states the specific action ('Cancel a subscription by id') with the resource clearly identified. It distinguishes from sibling tools like subscribe and list_subscriptions by focusing on the cancellation action.

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

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

The description provides relevant context (ownership enforcement) but does not explicitly specify when to use this tool versus alternatives. It implies that one should have a subscription id from subscribe, and mentions recent_alerts for historical data, but stops short of naming alternative tools or exclusions.

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

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

Even though annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, the description adds substantial behavioral context: the dual-path routing (structured vs grounded), the exact meaning of could_not_verify (check did not happen) versus unsupported (no source exists), the presence of verification_error{stage,detail}, and the pipeworx:// citation. This goes well beyond the annotations and is critical for correct caller behavior.

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

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

The description is dense but efficiently packed. Every sentence earns its place: trigger phrases, usage context, routing logic, return payload, and an explicit warning about could_not_verify. It is front-loaded with examples and contains 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 is remarkably complete for a complex tool. It covers inputs, process (routing), outputs (verdict taxonomy, citation, reasoning), and subtle error semantics. It even explains the tool's advantage over sequential calls, making it self-contained 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?

Both parameters (claim, tolerance_pct) have thorough descriptions in the input schema, giving 100% schema coverage. The description references some context ('exact percent-delta math') but does not materially expand the meaning of the parameters beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly identifies a specific verb and resource: 'natural-language claim verification against authoritative sources.' It opens with trigger examples like 'fact check' and 'verify the claim that…', and explicitly differentiates from sibling tools by describing the structured SEC EDGAR path for financial claims and the grounded pipeline for all other claims. It also notes it replaces 4–6 sequential calls, setting it apart.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains automatic routing based on claim type. However, it does not explicitly name alternatives or state 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.