Arcgis Linncounty

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds critical context: cost implications (free vs. BYO), flow of _apiKey, and detailed return structure per model. 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?

Three efficient sentences pack essential information: action, default, optional cost, return structure. No redundant words; front-loaded with core function.

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?

Fully explains input parameters, behavior, output format (per-model fields and combined view). No gaps given no output schema; covers all needed for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining default model, API key passthrough, and disambiguation role of context, exceeding 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 uses a specific verb ('probe', 'score') and identifies the resource ('LLMs', 'visibility'), clearly distinguishing from siblings like 'scan_competitor_ai_presence' which focuses on competitors. It states the output range explicitly.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default vs. API-key behavior. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it routes questions to many tools, returns structured answers with citation URIs, and is fast. Does not cover potential limitations like out-of-scope questions, but is fairly transparent.

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

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

Well-structured, front-loaded with key purpose, then usage guidance, then examples. Every sentence adds value 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?

Given tool complexity and good annotations, description explains what the tool does, when to use, return format (citation URIs), and differentiators. No output schema needed because return type is described.

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 full parameter descriptions. The description provides examples but does not add new meaning beyond what the schema already provides for the parameters.

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

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

Clearly states tool answers factual questions about real-world data using 4,552 tools across 1,160 sources. Distinguishes from siblings like ask_pipeworx_grounded and deep_research with specific guidance on when to use each.

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 advises to prefer this over web search for authoritative data. Provides detailed when-to-use and when-to-step-up scenarios, including examples and mentions it works on every tier.

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

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

Beyond annotations (readOnlyHint, openWorldHint), the description adds key behavioral traits: hallucination-resistance, extraction from tool result, explicit refusal reasons, and extra LLM call cost.

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?

Well-structured with front-loaded purpose. While dense, every sentence contributes value; could be slightly trimmed but remains effective.

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 (routing, extraction, refusal logic) and absence of output schema, the description provides a complete picture including response format, trade-offs, and use cases.

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 already covers all parameters with 100% description coverage. The description adds no parameter-specific details beyond the purpose, so baseline 3 is appropriate.

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

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

Description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes from sibling 'ask_pipeworx' by detailing the extraction behavior and response structure.

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 scenarios ('quoted, cited, or acted on') and when-not-to ('prefer ask_pipeworx for casual lookups'), including the cost trade-off.

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

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

The description extensively discloses behavioral traits beyond annotations, including fan-out logic, response shapes, resolver contract, parent_event extraction, news fallback mechanisms, safety short-circuits for low-confidence matches and closed markets, liquidity warnings, and resolution-rule risk. Annotations only indicate readOnly, idempotent, non-destructive; the description provides critical context for safe usage.

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

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

The description is very long and contains many examples and edge cases, which can be overwhelming. While it is well-organized with section headers, it could be more concise. The initial purpose is front-loaded, but the density of information may detract from quick comprehension. A more streamlined version would score higher.

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 (multiple classifiers, fan-out, resolver logic, error handling) and the absence of an output schema, the description provides comprehensive coverage of return values, safety mechanisms, and pitfalls. It explains all critical aspects an agent needs to correctly invoke and interpret the 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 description coverage is 100% for the three parameters, so the baseline is 3. The description repeats some parameter details (e.g., market input as slug/URL/text) but does not add significant new semantic information beyond what the schema already provides. The depth and include_raw parameters are adequately described in the schema, and the description does not elaborate further on these parameters.

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

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

The description opens with a clear statement of purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and the output (evidence packet + comparison). The tool's scope is distinct from sibling tools like 'polymarket_edges' or 'validate_claim', which address different aspects of Polymarket analysis.

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

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

The description explicitly gives usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also advises inspecting market_match_confidence before trusting the analysis block, providing guidance on when to be cautious. However, it does not explicitly state when not to use this tool or mention alternatives, which would elevate it to 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it pulls latest data, handles off-calendar fiscal years, results sorted by primary metric, and returns citation URIs. No contradictions.

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

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

Description is front-loaded with common queries and packs substantial information efficiently. Each sentence adds value, though slightly dense. No fluff.

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

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

Given complexity of two entity types and multiple metrics, description covers data sources, fiscal year handling, result sorting, and citation URIs. Lacks explicit return format details but sufficient for selection.

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%. Description enriches by explaining what data each 'type' pulls and gives concrete examples for 'values' (tickers/CIKs for company, drug names). This adds meaningful context beyond schema descriptions.

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

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

Description starts with natural language triggers and clearly states it performs side-by-side comparison of 2-5 companies or drugs. It distinguishes from sibling tools like entity_profile by specifying data sources and preference over 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?

Explicitly advises to prefer over sequential single-pack lookups and gives example triggers. It does not explicitly state when not to use, but the context is clear. The description also mentions replacing 8-15 sequential lookups, guiding priority.

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?

Describes internal process (decomposition, parallel routing, findings packet with gaps, no invention) and expected time. Aligns with annotations (readOnly, idempotent) and adds rich 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?

Long but well-structured with front-loaded critical info. Every sentence adds value, though some verbosity 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 no output schema, description adequately explains output structure, prerequisites, alternatives, limitations, and expected time. Complete for a complex tool.

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

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

Schema already covers parameters fully; description adds value by explaining depth enum values (quick=3, standard=5, thorough=8) and that question accepts broad/multi-part queries.

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

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

The description clearly states it performs grounded multi-source research across structured data, decomposing questions and returning findings with evidence. It differentiates from siblings like ask_pipeworx for single lookups and breaking news.

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

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

Explicitly says when to use (broad/multi-part structured questions) and when not (single lookup, breaking news), providing alternatives (ask_pipeworx). Also mentions account requirement and alternative for non-signed-in users.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly', adding behavioral context beyond annotations.

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

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

The description is well-structured: it starts with purpose, lists when to use, enumerates domains, explains what is returned, and ends with a call to action. Every sentence adds value 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?

With 6 parameters (5 aliases) fully documented in the schema, the description explains what the tool returns (lists of tools with schemas), includes default/max limit, and provides examples. No output schema is needed as the return structure is described. Completely adequate.

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

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

Schema description coverage is 100% with all 6 parameters documented. The description reinforces the query parameter's purpose by listing example domains ('analyze housing market trends') but does not add new semantic detail beyond the schema.

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

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

The description clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from siblings like 'search_datasets' by emphasizing this is a tool discovery 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?

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available'. Provides clear context but does not explicitly state when not to use it, though it's implied.

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

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

Description adds significant behavioral context beyond annotations: it is a single parallel call, fans out across multiple sources, soft-fails for patents (USPTO sunset), uses fallback for news (GDELT→GNews), and specifies return structure. No contradiction with annotations (readOnly, idempotent, non-destructive).

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 comprehensive but slightly long. It is front-loaded with examples and key guidance, and every sentence contributes value. Could be slightly more concise, but given the tool's complexity, the length is justified.

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

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

No output schema exists, but the description thoroughly explains return values (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and behavior (soft-fail, fallback). Covers data sources, limitations, and expected output, making the tool fully understandable 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?

Input schema has 100% coverage with descriptions. The description adds value by explaining that 'value' can be ticker or CIK (not names), and clarifies the restriction of 'type' to 'company'. This enriches the schema, though the schema itself is already descriptive.

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: providing a full cross-source profile of a US public company. It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and returned fields, and distinguishes from siblings by stating it is preferred over chaining individual lookups. The examples (e.g., 'tell me about X', 'research Acme') reinforce the 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?

Explicit guidance on when to use (holistic view) and what to avoid (names, which require resolve_entity first). Provides input format (ticker or CIK) and warns against unsupported inputs. Mentions alternative tools like resolve_entity for name resolution, and advises against chaining single-source lookups.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds minor context about 'previously stored' but doesn't significantly extend beyond annotations.

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

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

Two concise sentences with front-loaded action and no wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and tool relationships.

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

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

Schema has 100% coverage for the single parameter 'key' with description 'Memory key to delete'. Description repeats this without adding new semantic meaning.

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

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

The description uses a specific verb 'Delete' and resource 'previously stored memory by key', clearly distinguishing it from sibling tools like 'remember' and 'recall'.

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 ('context is stale, task is done, clear sensitive data') and mentions related tools ('Pair with remember and recall').

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 that it fetches the page, extracts title/description/links, and emits standard markdown. This provides useful behavioral detail beyond annotations.

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

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

The description is a single efficient paragraph, front-loaded with the core purpose, followed by process and use cases. Every sentence adds value with no redundancy.

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

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

The description fully covers what the tool does, its inputs, output format, and typical use cases. Despite lacking an output schema, it clearly describes the output as a text blob. For a simple tool, this is complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: an example URL for 'url' and default/max values for 'max_links'. This goes beyond the schema details.

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 an llms.txt file for a URL, specifying the target AI crawlers and output format. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning or visibility checking.

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 usage scenarios (client's site, own project, competitor audit) but does not explicitly state when not to use or mention alternatives. The context is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, indicating a safe, read-only operation. The description adds specific behavioral details about what the tool returns: field names and types, geometry type, record count, and capabilities. This provides useful context beyond the annotations.

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

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

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and output. Every word serves a function, and there is no unnecessary content.

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

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

Given the absence of an output schema, the description provides a high-level summary of the return values (fields, geometry type, record count, capabilities), which is sufficient for an agent to understand what to expect. However, more detailed structure (e.g., format of capabilities) would be beneficial but not critical.

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 input schema already documents the 'url' parameter well. The description reinforces the parameter's purpose with an example URL format, but adds no additional meaning beyond the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves an ArcGIS Feature/Map Service layer's schema, listing specific components: fields, geometry type, record count, and capabilities. The verb 'Get' and resource 'layer's schema' are specific, and it implicitly distinguishes from the sibling 'query_layer' which likely queries actual data rather than metadata.

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

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

The description indicates usage by providing a URL, which is clear. However, it does not explicitly state when to use this tool versus alternatives like 'query_layer' or other sibling tools. The context of getting schema vs. data is implied, but explicit guidance on when not to use it would improve clarity.

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?

Description lists returned fields and implies read-only nature, complementing annotations. Notes caller-specific scope and default active-only filtering.

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 purpose, efficient use of words. No filler.

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

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

Adequate for a simple list tool with one optional param. Lists return fields, which compensates for lack of output schema.

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

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

Schema coverage is 100% with description for 'include_inactive'. Description adds no extra detail beyond schema. Baseline 3 applies.

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

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

Clear verb 'list', specific resource 'subscriptions', and scope 'caller's active'. Distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly states when to use: review before adding more or find id to cancel. Lacks exclusions but provides 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?

Discloses rate limit of 5 per identifier per day, that it doesn't count against tool-call quota, and that feedback is read daily. Annotations already indicate no destructiveness, but description adds important behavioral context without contradicting annotations.

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

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

Description is concise (4 sentences) with front-loaded purpose, followed by usage guidance and constraints. No wasted words; each sentence adds value.

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

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

Given the tool's simplicity (feedback submission), the description fully covers purpose, usage, constraints, and parameter semantics. No output schema needed; description provides complete guidance for agent to use correctly.

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

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

Schema coverage is 100% with detailed descriptions for each parameter. Description adds extra guidance on how to formulate message (e.g., mention tools/packs, avoid end-user prompts) and maps type enum values, providing more context than schema alone.

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

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

Description clearly states the tool is for sending feedback (bugs, features, data gaps, praise) to the Pipeworx team. It specifies the exact purpose and distinguishes from sibling tools which are analytical or data retrieval tools.

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

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

Explicitly states when to use: for bugs, missing features, data gaps, or praise. Provides clear instructions: describe issue in terms of Pipeworx tools/packs, don't paste end-user prompt. Also mentions rate limits and that it's free.

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 safe, read-only behavior. The description adds value by explaining the tool is 'self-aggregating signal from CF analytics-engine, no PII, just (pack, tool, count)' and cached, which are useful behavioral details.

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

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

The description is concise (4 sentences) with a logical flow: main function, use cases, then technical details. No redundant information.

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

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

Despite lacking an output schema, the description adequately explains what is returned (top tools, packs, volume) and caching behavior. For a simple, read-only aggregate tool, this is complete.

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

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

The description adds meaning beyond the schema: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', effectively complementing the enum parameter's description.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, with a specific verb 'returns' and resource. It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on trending.

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?

Three explicit use cases are listed (discovering hot data, confirming popular tool, aligning use case). While it doesn't say when not to use or name alternatives, the context is clear and helpful.

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 indicate readOnly, openWorld, idempotent, not destructive. The description adds extensive behavioral context: how scans work (top 200 markets), partition checks, Jaccard similarity threshold, placeholder filtering, fill checks against live order book, and handling of overround only at last-trade. This far exceeds annotation scope and reveals key behaviors for safe use.

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

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

The description is detailed and well-structured, with clear sections and front-loaded purpose. While comprehensive, it is somewhat lengthy; however, every sentence contributes value. The structure makes it easy to parse, earning a high score just short of perfect due to slight verbosity.

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

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

Given the complexity of arbitrage detection, the absence of an output schema, and rich sibling context, the description is remarkably complete. It explains the algorithm, filters, response shape, fill check, and edge cases. No gaps remain for an agent to understand what the tool does and when to use it.

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

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

Parameters event and topic have schema descriptions that explain their types (slug, full URL, seed question) and modes. The tool description greatly enriches these by providing usage recommendations, examples, and behavioral implications (e.g., event walks child markets; topic searches related events). Schema coverage is 100%, but the description adds significant semantic 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 explicitly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (trending_scan, event, topic) and explains the mechanism. This differentiates it from sibling tools like polymarket_edges and 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?

The description provides detailed guidance: when to call with no args (trending_scan), when to pass event (recommended for specific markets), and when to pass topic (cross-event scanning). It explains the trade-offs and even references an alternative tool (polymarket_fill_risk) for custom sizing. It also includes conditions for not trading (realizable_edge_pp ≤ 0).

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, which the description does not contradict. The description adds rich behavioral context: caching (1h at KV level), detailed model family mechanics (e.g., partition_overround with per-sport alpha, placeholder filters), diagnostics for empty segments, and explanations of knobs. 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 very long (approx. 500 words) and not concise, but it is well-structured with clear sections for each model family and response details. Every sentence provides useful information, but the verbosity may reduce quick parsing by an 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?

Given the tool's complexity (3 model families, 9 parameters, no output schema), the description is fully complete. It explains the response structure (by_segment, fed_candidates, diagnostics), caching, why Fed bets are excluded, and all knobs. The agent has everything needed to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description groups parameters into knobs (e.g., 'tradeable-edge filters') and adds context like 'min_partition_leg_kelly' applying to per-leg Kelly, but this adds marginal value over schema descriptions. The description does not substantially augment parameter semantics beyond the schema.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', providing a specific verb and resource. It distinguishes from sibling tools by focusing on edge discovery across three model families, making its purpose unmistakable.

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

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

The description explicitly says it is built for 'what should I bet on today' and helps agents discover opportunities without paging hundreds of markets, indicating when to use. However, it does not explicitly state when not to use or mention alternatives, though the three model families and knobs provide implicit 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: it reads snapshots, explains data derivation (daily closes, net of default slippage), limits (60-day TTL, from when snapshotting enabled), and clarifies that gaps occur when no scan happened. 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 verbose but packed with useful information. It has a logical structure (question, args, response structure, limits), but some details could be condensed. It earns its sentences, but could be slightly shorter for improved conciseness.

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

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

Despite no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) and key derived fields (trend, decay_pp_per_day, lifespan_days). Limitations are clearly stated. The parameter explanations and response details make the tool's behavior fully understandable.

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

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

Schema description coverage is 100% for both parameters. The description adds meaning: default values for days (14) and window (1wk), family options (24hr, 1wk, 1mo), and the concept of 'snapshot family'. This goes beyond the schema description.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical behavior rather than raw current edges.

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

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

The description implies usage for assessing edge persistence, but does not explicitly state when to use this tool over alternatives (e.g., polymarket_edges) or provide when-not-to-use guidance. No exclusions or alternative tool names are mentioned in the description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details beyond annotations: it walks the order book, returns a verdict (clean/degraded/cannot_fill), capture_ratio, thin_legs, and forced_directional_risk. 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 relatively long but well-structured with capital-letter emphasis for modes and key points. It front-loads purpose, then details each mode, then usage guidance. Every sentence adds value, though it could be slightly more concise by breaking into sections.

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

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

With no output schema, the description fully explains return values for both modes (top_of_book, vwap_fill_price, slippage_pp, etc.) and includes risk context. Given 4 parameters and no output schema, it is comprehensive.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains the requirement for either market or event, default sides, interpretation of size_usd for buys vs sells in single-market mode, and settlement notional for basket mode. This exceeds mere schema repetition.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, each with specific explanations. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to use (partial fills convert arb into directional position) and provides context on risks.

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 read-only/idempotent safety. Description adds extensive behavioral details: how spreads are calculated (Kalshi minus Polymarket), conditions for compatibility_warning (non-equivalent bet shapes, semantic mismatch), temporal alignment importance, and skipped cross-type/subtype counters. 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?

Description is thorough but somewhat lengthy. It is well-structured, starting with purpose, then modes, response format, and safety fields. It could be slightly more concise, but no single sentence is wasted given the tool's complexity.

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

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

Despite no output schema, the description fully explains the response structure (raw probabilities, matched spreads, compatibility fields, temporal alignment). All critical behavioral aspects are covered, making the tool usable without additional 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?

Schema has 100% parameter coverage with descriptions. Description adds value by explaining the two modes and override behavior, plus providing examples. This supplements the schema's basic descriptions, justifying a score above baseline.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same question. Distinguishes from siblings like polymarket_arbitrage by specifying the two-venue comparison. The verb 'spread' and resource 'Polymarket-Kalshi' are specific.

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 describes two modes (topic shortcut vs explicit tickers), explains when each is appropriate, and warns that most pre-mapped topics return compatibility warnings today. Provides guidance on interpreting safety fields to determine if spreads are meaningful.

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, destructiveHint. The description adds that it returns 'attribute rows (and geometry)' and provides a sampling pattern, aligning with and enhancing 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 three sentences, front-loaded with the purpose, and every sentence adds value with no redundancy.

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

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

For a tool with 6 parameters and no output schema, the description adequately covers purpose, parameters, returns, and usage. It lacks detailed return structure but provides good context.

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

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

All 6 parameters have schema descriptions (100% coverage). The description adds semantics like 'SQL-like', 'comma-separated', default '1=1', and gives a concrete example query, 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 verb 'Query' and the resource 'ArcGIS Feature Service / Map Service layer', and links to sibling tool 'search_datasets' for obtaining the URL, distinguishing it from other tools.

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

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

It specifies the context (from search_datasets) and gives an example usage ('where="1=1" + out_fields="*" to sample'), but does not explicitly mention when not to use it or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds scoping details (anonymous IP, BYO key hash, account ID) and pairing context, providing value beyond annotations 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?

Four sentences, each purposeful and front-loaded with the action. No redundancy or fluff; the description is compact yet comprehensive.

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

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

Given the tool's simplicity (one optional parameter, no output schema) and the presence of clear annotations, the description covers all necessary aspects: purpose, usage context, behavioral nuances, and relationship to siblings. It is fully adequate.

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

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

Schema coverage is 100%. The description adds the key behavioral detail that omitting the key lists all saved keys, which goes beyond the schema's description of 'omit to list all keys' and provides practical usage insight.

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

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

The description clearly states the tool retrieves values saved via 'remember' or lists all keys when the 'key' argument is omitted, distinguishing it from sibling tools like 'remember' and 'forget'.

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

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

The description explicitly says when to use the tool ('to look up context the agent stored earlier... without re-deriving it from scratch') and mentions pairing with remember and forget, but lacks explicit when-not-to-use instructions.

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 declare readOnlyHint: true and destructiveHint: false, suggesting no side effects. However, the description describes a mark_read parameter that flags events as read, which is a mutation of state. This contradicts the read-only hint, making the description misleading. Additionally, the openWorldHint is consistent with the description that results can change, but the side-effect contradiction lowers the score.

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 long: the first sentence states the core purpose, the second details return fields, and the third covers parameters and usage. Every sentence is informative and no words are wasted. It is front-loaded 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 there is no output schema, the description adequately explains that each returned alert carries source, citation_uri, and raw payload. It also mentions the alternative HTTP endpoint and that polling works fine. However, it does not discuss pagination beyond the limit parameter or describe edge cases like empty results. For a simple polling tool, this is sufficient but not exhaustive.

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

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

The schema covers all 5 parameters with descriptions, and the description adds value by providing examples (e.g., 'sec_8k' for type), clarifying the 'since' parameter behavior, explaining the mark_read side effect, and noting the default limit of 50. This goes beyond the schema descriptions.

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

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

The description clearly states the action ('Pull fired events from your subscription feed') and specifies the resource (persisted feed of alerts). It distinguishes from sibling tools like list_subscriptions or subscribe by focusing on event retrieval. The description also lists key fields in each return item (source, citation_uri, raw payload), making the purpose very specific.

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 mentions that polling works fine and provides an alternative HTTP endpoint for scripts/dashboards, giving context for when to use the tool vs. other access methods. However, it does not explicitly compare to sibling tools like list_subscriptions or subscribe, but the tool name and purpose are self-explanatory enough. The guidance is clear but not exhaustive.

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

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

Annotations already indicate a safe, read-only tool. The description adds value by detailing the fan-out to SEC EDGAR, GDELT/GNews fallback, and USPTO with soft-failure notes. Could mention potential rate limits or performance, but overall transparent.

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

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

The description is well-organized, starting with examples and purpose. Each sentence adds value, but it is slightly long. Could be trimmed without losing clarity.

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

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

Despite no output schema, the description summarizes the return structure (changes[], total_changes, citation URIs). It covers multiple sources and fallback behavior. Missing details on error handling or specific fields, but sufficient for the complexity.

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

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

Schema coverage is 100% with descriptions. The description adds context: 'since' accepts ISO or relative shorthand (e.g., '30d'), and 'value' accepts ticker or CIK. This clarifies usage 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 explicitly states 'change feed for a company' and provides concrete query examples. It also distinguishes from the sibling tool entity_profile, which covers static profiles.

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

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

The description gives explicit usage examples ('What's new with X', 'latest on Y') and instructs to use entity_profile for static profiles, providing clear when-to-use and when-not-to-use guidance.

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

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

Adds significant context beyond annotations: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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?

Single paragraph of four sentences, front-loaded with purpose. Every 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?

Complete for a simple 2-parameter tool with no output schema. Covers scope, persistence, and usage pairing thoroughly.

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

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

Schema coverage is 100% with descriptions for both key and value. The description reinforces the key-value pairing with examples but adds no additional syntax or format details. Baseline 3 is appropriate.

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

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

Clearly states the verb 'save data' and resource 'key-value pair' for reuse across sessions. Distinguishes from siblings 'recall' and 'forget' by mentioning them as paired tools.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward' with examples. Mentions pairing with recall and forget, giving alternatives. Lacks explicit when-not-to-use but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds internal cascading behavior ('replaces 2-3 manual lookups'), which is consistent and adds value beyond annotations.

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

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

Concise paragraph with examples and key info front-loaded. No fluff, but could be slightly more structured (e.g., bullet points) for easier scanning. Still highly efficient.

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, description compensates by detailing return values per type. Covers essential behavior for a lookup tool. Annotations handle safety. Minor omission: no mention of error handling or limits, but not critical.

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

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

Schema has 100% coverage, but description greatly enriches semantics: explains what each type returns (ticker, CIK, company name for company; RxCUI, ingredient, brand for drug) and acceptable value formats (e.g., 'ozempic', 'metformin').

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 starts with concrete examples and states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It lists supported entity types and their outputs, clearly distinguishing the tool's purpose from siblings like entity_profile.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides detailed type-specific usage (e.g., inputs and outputs for company and drug). Lacks explicit when-not-to-use alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds behavioral insight by explaining the composite probing and ranking process, and details output fields (score, confidence, signal density), providing context beyond annotations.

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

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

The description is three concise sentences plus an example, front-loaded with purpose, and every sentence adds essential information 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?

Given the tool's complexity (composite of another tool, multiple parameters, no output schema), the description adequately explains purpose, process, and output fields. It could specify output format more concretely but is sufficient.

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?

With 100% schema coverage, the description adds meaning by explaining that the first entity is treated as 'subject' for narrative and by elaborating on the context parameter's purpose, enhancing understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, details the process of probing each entity with ai_visibility_check and ranking, and distinguishes itself from the sibling ai_visibility_check tool.

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

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

The description provides explicit usage context for competitive AI-marketing audits with an example question, and implies when to prefer this over the sibling ai_visibility_check, though it does not explicitly state when not to use or list exclusions.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds transparency about partial failures (sources_failed) and potential latency (5-30s for first measurement). 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?

Front-loaded with purpose, then explains components, usage, return values, ecosystem scope, and failure handling. Each sentence adds value. Slightly lengthy but justified by tool 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?

No output schema, so description fully details return fields: summary block fields, per-advisory details, links, alternative versions. Covers error handling and data sources. Complete for this composite 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% with descriptions for both parameters. Description adds extra detail not in schema: scoped packages accepted ('@types/node'). Also clarifies default version behavior, though schema already states it. Adds value beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, specifying criteria (safe, popular, small) and giving an example query. It distinguishes from siblings by noting it's npm-only in v1, which no other sibling covers.

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 describes when to use: when agent asks about package safety, popularity, or size. Also specifies when not to use: non-npm ecosystems. Mentions graceful degradation and timeout behavior for bundlephobia.

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, destructiveHint. The description adds value by detailing the return structure and the purpose of the url, which is not covered by annotations. 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 a single paragraph, concise, and front-loaded with the core purpose. Every sentence adds value, no fluff.

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

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

Despite no output schema, the description fully explains the return fields (name, summary, record_count, owner/org, url) and hints at usage with query_layer/layer_info. Covers all necessary context 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 descriptions for all 3 parameters. The description adds context by mentioning 'keyword' as the query parameter and explaining that org_id overrides the default Linn County GIS. This enhances understanding beyond the schema.

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

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

The description clearly states the tool searches Linn County GIS open geospatial datasets by keyword and returns specific fields (name, summary, record_count, owner/org, Feature Service url). It distinguishes from siblings by mentioning query_layer and layer_info as follow-up tools.

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

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

The description provides good context for when to use the tool (searching datasets) and directs to subsequent tools (query_layer, layer_info) for further actions. However, it does not explicitly exclude alternative use cases or specify when not to use it.

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

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

Adds significant behavioral detail beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows', 'cap is 200K chars (longer inputs are truncated and flagged)', and 'every passage carries an offset so the agent can verify a verbatim quote'. Annotations already indicate read-only, idempotent, non-destructive, so description enriches with algorithm and limitations.

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?

Efficient single paragraph of 5 sentences, front-loaded with purpose, then details on mechanics, pairing, and limits. No filler or repetition.

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?

Tool has 3 params, no output schema, but rich annotations. Description explains return format (top-N passages with offsets and scores), algorithm details, truncation behavior, and how it pairs with another tool. Given the tool's complexity, this covers all needed context for an AI agent to use it correctly.

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

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

Schema coverage is 100% with descriptions. The description adds contextual examples (e.g., 'supply-chain risk' for query) and reinforces the character limit for text. While schema already explains parameters, the description's examples and pairing guidance add value beyond schema.

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

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

Description clearly states 'Semantic search INSIDE a fetched record', identifies the verb (search) and resource (text from a fetched record), and distinguishes from siblings by mentioning it pairs with ask_pipeworx_grounded. Examples like 'SEC 10-K body' and 'article' make the purpose concrete.

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: 'when the record is too big to cram into the prompt'. Also provides guidance on not using it for full documents by mentioning a pairing alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document'.

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

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

Beyond annotations, the description discloses key behaviors: OAuth requirement, always-on feed, optional delivery channels with constraints (SMS cap, webhook auto-disable after failures), and one-time webhook secret. This adds substantial value.

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 containing all necessary information. While it is not broken into sections, it front-loads the main purpose and return value. Could be slightly more structured, but content is valuable.

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 3 parameters (2 required) and no output schema, the description covers the subscription types, delivery options, and return value (subscription id). It mentions the feed endpoint but could be more explicit. Overall, it is fairly 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 has 100% coverage, and the description enhances it with concrete examples (e.g., sec_8k items codes, polymarket_edge topics) and detailed delivery options including SMS verification and webhook signing. This adds significant meaning.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific action (create) on a resource (subscription), and it distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explains requirements (OAuth account) and provides examples for each subscription type, but it does not explicitly state when not to use this tool versus alternatives like recent_alerts or list_subscriptions. However, the context is fairly clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that the tool uses a live catalog and can be called without arguments, providing useful behavioral context beyond annotations.

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

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

The description is well-structured with front-loaded alternative question phrasings, a clear list of categories, and a call-to-action. It is slightly long but every sentence delivers necessary information 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?

Given no output schema, the description adequately explains the return format (category-bucketed examples with tool+argument shapes). Together with the annotations (openWorldHint, idempotentHint), it provides complete context for an agent to use this tool effectively.

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

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

Schema description coverage is 100%, so the schema already defines the parameter. The description adds value by providing example values ('finance', 'pharma', 'betting') and explaining the effect of omitting the parameter, which aids understanding.

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

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

The description clearly states that the tool generates example questions, organized by category, and distinguishes itself as the onboarding entry point for new agents. It uses specific verbs like 'returns category-bucketed example questions' and mentions the exact tools and argument shapes, making its purpose unambiguous.

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

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

The description explicitly instructs to use this tool 'FIRST when you do not yet know what Pipeworx can do' and to learn how to call meta-tools. It provides clear guidance on when to use it and mentions the optional topic parameter for focus, effectively differentiating from siblings.

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

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

Annotations already indicate non-destructive and idempotent behavior. The description adds valuable behavioral context: the row is deactivated not deleted, historical events remain via recent_alerts, and ownership is enforced. 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?

Two sentences with no wasted words. The first sentence front-loads the action and ownership, the second explains the deactivation behavior. Every sentence serves a purpose.

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

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

For a simple single-param tool with no output schema, the description covers purpose, ownership constraint, deactivation behavior, and impact on historical data (referencing recent_alerts). No gaps identified.

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 'id' is fully described in the input schema (uuid from subscribe). The description adds no new meaning beyond restating 'by id'; schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource ('subscription'). It distinguishes from sibling tools like subscribe (which creates) and list_subscriptions (which lists).

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

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

The description provides clear context for when to use the tool (to cancel a subscription) and includes a constraint (ownership enforcement). It does not explicitly exclude alternative scenarios, but the guidance is sufficient given the simple tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral details: data sources (SEC EDGAR + XBRL), return values (verdict types, structured form, citation, delta), and efficiency gains. 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 well-structured, starting with trigger phrases and ending with return details. Each sentence adds value, though slightly verbose. Front-loading is effective.

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 the return structure (verdict, values, citation, delta) and domain constraints. It adequately informs an agent about inputs, outputs, and limitations.

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 'claim' is described with examples in the parameter description and elaborated in the tool description (supported claim types). Schema coverage is 100%, and the description adds meaningful context 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 explicitly states the tool's purpose as natural-language claim verification against authoritative sources, with clear trigger phrases and examples. It distinguishes from siblings by noting it replaces multiple sequential calls, making the purpose unambiguous.

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

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

The description advises use whenever factual verification is needed and specifies the supported domain (company-financial claims for public US companies). It lacks explicit exclusions or alternate tools, but the context is sufficient for typical scenarios.

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