Arcgis Delawareco

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds that default model is free, but probing Anthropic requires a BYO key and direct charges. Also describes return structure. 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?

Two sentences: first sentence states purpose and scope, second sentence details options and returns. 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?

No output schema, but description fully explains return structure (per-model {score, confidence, signals, raw_response} + combined). Covers all parameters, use cases, and behavioral notes. No gaps.

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

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

Schema coverage is 100%, and description adds valuable context: entity is the thing to ask about, models defaults to workers-ai, _apiKey is only needed for Anthropic and is passed through, context helps disambiguate. Explains payment model for Anthropic.

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 it probes LLMs for knowledge about a business/brand/product/topic and scores visibility 0-100 per model. Distinguishes from siblings (many are Pipeworx or polymarket specific) by focusing on AI visibility audits.

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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Explains when to use optional parameters like `models` and `_apiKey`. Does not explicitly name alternatives but context makes it 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, destructiveHint. Description adds context: returns structured answer with citation URIs, works on every tier, one fast call. 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?

Well-structured with clear sections, examples, and comparisons. Slightly verbose but all content earns its place. Front-loaded with key guidance.

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 (6 params, no output schema), description covers purpose, usage, alternatives, behavior, and examples comprehensively. No gaps for agent selection and invocation.

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

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

Schema coverage 100% with descriptive aliases and examples. Description does not add parameter-level detail beyond schema, but schema itself is sufficient. Baseline 3.

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

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

Clear verb+resource: 'routes the question to the right one of 4,552 tools across 1,160 verified sources'. Distinguishes from siblings like ask_pipeworx_grounded and deep_research with specific guidance.

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 'PREFER OVER WEB SEARCH' with detailed when-to-use scenarios, examples, and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant, deep_research for broad queries).

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the internal process: picks the right tool, fetches data, extracts answer only from tool result. Discloses return structure with fields like evidence, confidence, refusal_reason, and refusal causes. No contradiction with annotations.

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

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

The description is fairly long but each sentence adds value; it front-loads the key purpose and trade-offs. Could be slightly more concise but is well-organized and informative.

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

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

Given the tool's complexity (many siblings, grounding behavior, refusal reasons), the description is thorough: covers routing, return structure, usage guidance, extra cost, and failure modes. No output schema but the description explains return values sufficiently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond listing aliases for the 'question' parameter, which is already documented in the schema. It does not provide additional meaning or constraints.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and contrasts it with sibling ask_pipeworx, noting that it extracts answers only from tool results and returns evidence. It explicitly distinguishes from other tools and lists use cases like financial verdicts, legal claims, etc.

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: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups' because of extra LLM call cost. Mentions alternatives and provides clear context for agent decision-making.

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

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

The description goes far beyond annotations (readOnlyHint, idempotentHint, etc.) by detailing fan-out behavior, safety mechanisms (low-confidence short-circuit, closed market handling), response shapes, resolver contract, parent event extractor, news fallback logic, wide spread handling, and resolution-rule risk. No contradictions with annotations. This level of detail fully informs the agent of the tool's behavior.

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

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

The description is very long (~600+ words) and dense. While every sentence adds value, the length could overwhelm an agent. It is structured with headings (e.g., 'RESPONSE SHAPES', 'RESOLVER CONTRACT') but lacks front-loading of the most critical information. A more concise version could improve readability.

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

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

Given the tool's complexity (multiple classifiers, fan-out examples, safety mechanisms, resolver contract, parent event extraction, news fallback, resolution-rule risk), the description is remarkably complete. It covers input handling, output structure, edge cases, and interpretation guidance. Without an output schema, the description adequately explains return values.

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%; all three parameters have descriptions. The tool description adds operational context: it clarifies the market input flexibility (slug, URL, question text), explains the 'depth' parameter effect on fan-out scope, and the 'include_raw' parameter on response size. This adds meaning beyond the schema, justifying a 4.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). The verb 'research' and resource 'Polymarket bet' are specific, and the scope (single call, fan-out) distinguishes it from sibling tools that focus on edges or arbitrage.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive guidance on interpreting results, including inspection of resolver contract, parent event extraction, and resolution-rule risk. However, it does not mention when not to use it or suggest alternatives, which keeps it from a 5.

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

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

Annotations already indicate safe, idempotent behavior. The description adds significant context: specific data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with query examples, then provides essential details about behavior, data sources, and output. Every sentence adds value without redundancy. Efficient and well-structured.

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

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

Given the complexity (two entity types, multiple data sources) and no output schema, the description covers data sourcing, sorting, fiscal year handling, and return format (paired data + citation URIs). Complete guidance 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 description coverage is 100%, with clear descriptions for both parameters. The tool description does not add new parameter semantics beyond what the schema provides, though it reinforces with examples. 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 it performs side-by-side comparisons of 2–5 companies or drugs in one call, with explicit query examples like 'X vs Y' and 'rank these companies'. It distinguishes itself from siblings by advocating 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?

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It also explains the data pulled for each entity type, aiding decision-making.

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 return format (findings packet with evidence, confidence, source, citations, gaps), expected duration (15-60s), and limitations (returns empty gaps for topics not in structured catalog). Adds value beyond annotations which already indicate read-only, 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?

Description is long but well-structured, front-loaded with critical info (account requirement, alternative tools). Every sentence adds value, though could be slightly more concise. Structured as actionable guidance followed by detailed explanation.

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 (research tool with many sources, parallel execution), the description covers authentication, alternatives, use cases, return format, limitations, and expected time. No output schema, so description adequately explains return values.

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

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

Schema descriptions cover both parameters, but the description adds meaning: explains depth values (quick=3, standard=5, thorough=8 facets) and that thorough requires paid plan. For question parameter, clarifies broad/multi-part is okay. Adds significant 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 performs grounded multi-source research across 1160 structured data sources, decomposes questions into facets, and routes to 4552 tools in parallel. It distinguishes from siblings by specifying when to use ask_pipeworx instead (for single lookups, current news, or if not signed in).

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 guidelines: includes account requirement, paid plan for thorough depth, alternatives (ask_pipeworx for single lookups and news), and when not to use (breaking news). Provides clear context for optimal use.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) are consistent with a read-only discovery tool. Description adds value by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' 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 well-structured with three clear parts: purpose, usage, and return value. Sentences are informative but not overly verbose. Could be slightly more concise, but overall 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 adequately explains what is returned. It also provides context that this is a first-step discovery tool. Covers the parameter count of 6 and no nested objects well.

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%. Description adds meaning by listing multiple query aliases (task, q, description, search) and specifying default limit of 20 and max of 50, which are not in individual parameter descriptions.

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

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

Description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and uses strong verbs like browse, search, look up. Distinguishes from sibling tools as the primary discovery tool.

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

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

Explicitly says when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' Does not list alternatives 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds specific behavioral context: it fans out across multiple sources, details return fields (cik, filings, fundamentals, patents, news, LEI), warns that patents PatentsView API may soft-fail after May 2025, and restricts input to ticker/CIK. No contradiction with annotations.

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

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

The description is a single dense paragraph that front-loads examples and then details the output. Every sentence adds value, but it could be slightly more structured (e.g., bullet points for return fields) for easier scanning. Still very 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?

Given no output schema, the description fully explains the complex return shape (filings with URIs, fundamentals sorted by period_end, news fallback, etc.). It also mentions known limitations (patent API sunset, name resolution requirement). Completely adequate for an AI agent to understand the tool's capabilities 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?

Schema coverage is 100% with schema descriptions, but the description adds critical nuance: 'value' must be a ticker or zero-padded CIK (not names), and 'type' is currently only 'company'. This goes beyond the schema's enum 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 produces a 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example intents (e.g., 'Tell me about X', 'research Acme') and explicitly differentiates from sibling tools like resolve_entity by noting that names require a prior resolution step.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also tells the agent to use resolve_entity if only a name is available, providing clear when-to and when-not-to 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 indicate destructiveHint=true, and description confirms deletion. Adds context that it clears 'sensitive data' and relates to agent-saved memories. No contradiction.

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

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

Two sentences, front-loaded with purpose, no fluff. Efficiently conveys all needed 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?

Lacks description of return value or failure behavior. However, for a simple delete action with clear schema and annotations, it is largely 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 has 100% coverage with 'key' parameter described as 'Memory key to delete'. Description adds no further parameter-specific meaning beyond restating 'by key'.

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 verb 'delete', resource 'memory', and specifies deletion 'by key'. It distinguishes from sibling tools 'remember' and 'recall' by indicating its opposite 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?

Provides explicit usage scenarios: stale context, task completion, clearing sensitive data. Mentions pairing with 'remember' and 'recall' but does not explicitly state when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, and open-world behavior. The description adds that the tool fetches the page, extracts title/description/key links, and emits markdown format, disclosing network activity 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 three sentences: first defines purpose, second explains the process, third lists use cases. It is front-loaded and concise, with no wasted words. Slightly more structure (e.g., bullet points) could improve readability, but it is efficient for its length.

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

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

For a simple tool with two parameters and no output schema, the description provides sufficient context: it explains the output format (single text blob), the process, and typical use cases. It lacks error handling details but is complete enough for an AI agent to understand and invoke the tool correctly.

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

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

Both parameters ('url' and 'max_links') have clear descriptions in the input schema (100% coverage). The tool description does not add any semantic information beyond what the schema provides, so it meets the baseline of 3.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying the action (generate), resource (llms.txt), and target users (AI crawlers). It distinguishes itself from all siblings, none of which claim to generate llms.txt files.

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 lists specific use cases (getting a client's site indexed, drafting for own project, auditing competitor) that provide clear context for when to use this tool. It does not explicitly state when not to use it or mention alternative tools, but the context is sufficient.

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 the tool as read-only, idempotent, and non-destructive. The description adds value by specifying the exact data returned (fields, geometry type, record count, capabilities), which improves behavioral understanding beyond annotations. However, it does not disclose additional traits like rate limits or error handling.

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

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

Single sentence with no extraneous words. Every part is essential: verb, resource, output list. Front-loaded with key action and resource, followed by specifics. 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?

For a simple schema retrieval tool with one parameter and no output schema, the description fully covers what the agent needs: it explains the input (URL with example), the outputs (fields, geometry type, count, capabilities), and the context (ArcGIS layer). No gaps.

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

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

Schema coverage is 100% (one parameter 'url' with description). The tool description adds only the example URL format and the phrase 'by url', which largely repeats what the schema already provides. No additional semantic information beyond the schema.

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

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

Description uses specific verb 'Get', identifies the resource ('ArcGIS Feature/Map Service layer's schema'), and lists the exact outputs (fields, geometry type, record count, capabilities). This distinguishes it from sibling tools like 'query_layer' which would return data rather than schema.

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

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

The description states the tool retrieves schema by URL but does not explicitly guide when to use this versus alternatives (e.g., 'query_layer'). There is no mention of prerequisites, context, or when not to use it. Usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds context about return fields and usage, but no behavioral traits beyond 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?

Two sentences, front-loaded with purpose and return fields, no wasted words. Highly concise.

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

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

Given rich annotations, full schema coverage, and no output schema, the description adequately covers purpose, returns, and usage. Missing details on pagination if any, but that is a minor gap.

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

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

Schema coverage is 100% with clear description for the single parameter. Description does not need to add semantics beyond 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?

Description clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from sibling tools subscribe and unsubscribe. Also lists return fields.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use guidance.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: rate-limited to 5 per day, free, doesn't count against quota, team reads digests daily, and feedback affects roadmap. No contradictions with annotations.

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

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

The description is concise (4 sentences) and front-loaded with purpose. Every sentence adds essential guidance: what to do, when to use, how to format, team process, and constraints. 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 feedback tool with no output schema, the description covers purpose, appropriate use cases, formatting requirements, rate limits, and team impact. It is complete and leaves no ambiguity about how the feedback is processed.

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

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

Schema coverage is 100% and includes detailed enum descriptions. The description adds further value by explaining the expected format (1-2 sentences, 2000 chars max), how to structure context (tool, pack, vertical), and reiterating the enum definitions with clearer usage guidance.

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

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

The description clearly states the tool is for sending feedback about broken, missing, or needed functionality in Pipeworx tools. It explicitly lists feedback types (bug, feature, data_gap, praise), distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

The description provides explicit when-to-use guidance: use for bugs (wrong/stale data), feature requests, data gaps, or praise. It also tells what not to do (don't paste end-user prompts), and specifies formatting and rate limits (5 per day). This clearly differentiates from sibling tools.

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

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

Adds meaningful context beyond annotations: self-aggregating signal, no PII, caching durations. Annotations already declare readOnly/idempotent, but the description enriches with operational 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?

Well-structured with front-loaded summary, bullet-like use cases, and caching info. Efficient but could be slightly shorter 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?

Single optional parameter, no output schema needed as description explains return values (tools, packs, volume). Caching info and scope are sufficient for a read-only trending tool.

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

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

Schema coverage is 100%, so baseline is 3. The description restates the window options but doesn't add new meaning beyond the schema's enum and 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 window, distinguishing it from sibling tools like discover_tools by focusing on trending usage.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, and checking alignment) providing clear context for when to use this tool versus others.

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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds rich behavioral context: details monotonicity checks, partition_sum, Jaccard similarity threshold, placeholder filter, and fill check logic. 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 long but well-organized with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though some redundancy could be trimmed. Very informative.

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

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

Given complexity (2 params, no output schema), description is thorough: explains return structure, edge cases (placeholder slugs, fill check), and references sibling tool for custom sizing. 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?

Schema describes both parameters; description adds substantial meaning: for 'event' explains it walks child markets and computes partition_check, for 'topic' explains cross-event scanning and semantic anchor. Provides examples and clarifies behavior 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, and differentiates 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?

Explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan...', 'pass event for the strongest per-event partition_check', 'topic for a themed cross-event scan'. Recommends 'event' for specific markets and warns when not to trade via fill check. References sibling tool for custom sizing.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing the internal models, response structure (by_segment, diagnostics), caching behavior (1h at KV level), edge calculation specifics, and tradeable-edge knobs. This fully discloses the tool's behavior.

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

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

The description is quite verbose, spanning multiple paragraphs with extensive detail. While it is well-structured with separate sections, it is not front-loaded and could be more concise. The first sentence effectively conveys the purpose, but the overall length may require effort to parse.

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

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

Despite the absence of an output schema, the description thoroughly explains the response structure, including top-level fields, diagnostics, and segment details. It also covers caching, edge calculation, and parameter effects, making it 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?

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining the purpose of each knob (e.g., min_kelly is half-Kelly, min_edge_pp is net of slippage) and how they interact, which 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also specifies the target use case, 'what should I bet on today,' which distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description provides usage context for the tool's output (e.g., Fed bets excluded from ranking) and explains the three model families, but it lacks explicit guidance on when to use this tool versus alternative tools or when not to use it. No direct comparisons with siblings are provided.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it uses daily snapshots, provides time-series data, trend classification, decay metrics, and expired opportunities with lifespan. It also discloses limitations like history bounded by 60-day TTL and no intraday data. 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 informative but somewhat lengthy. It front-loads the purpose and then provides detailed return structure. Every sentence adds value, though it could be slightly more concise by grouping related info. Still efficient overall.

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

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

No output schema is provided, so the description must fully explain return values. It does so thoroughly: describes tracked[] with fields (edge_pp_net time-series, first_seen, trend, decay_pp_per_day), expired[] with lifespan_days, and snapshot_dates[]. Also mentions limitations (60-day TTL, no intraday). This is complete for a complex tool.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema: specifies defaults (days=14, window='1wk'), constraints (days max 30), and explains window as snapshot family. This enriches understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers specific questions about edge duration and trends, and distinguishes from sibling tool 'polymarket_edges' by focusing on time-series and trend 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 provides context on when to use this tool (e.g., differentiating between a fresh edge and an old edge) but does not explicitly state when not to use it or provide direct alternatives. The implied usage is clear but lacks explicit exclusion criteria.

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 behavior. The description adds beyond annotations by warning that 'theoretical overround on thin books is not capturable' and that 'partial basket fills convert an arb into an unhedged directional position'. No contradiction with annotations.

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

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

The description is well-structured with capitalized mode labels and bullet-like details. Each sentence adds value, from purpose to return fields to usage warnings. No unnecessary text, front-loaded with key 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 no output schema, the description fully details return values for both modes, including field names and their meanings. It also covers edge cases (thin books, partial fills) and provides complete guidance for an AI agent to use the tool effectively.

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

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

Schema description coverage is 100%. The description explains parameter meanings beyond the schema, such as how size_usd is interpreted differently in single-market vs basket mode, and the auto side detection for baskets. Adds significant value.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes with explicit return fields. It also differentiates from sibling tools by specifying its use before acting on polymarket_arbitrage or polymarket_edges signals.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (partial fills convert arb into unhedged directional position) and provides context for not using it in other scenarios.

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

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

Annotations already mark this as read-only and idempotent. The description goes far beyond by detailing the two modes, response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning, temporal_alignment, skipped counters), and how to interpret results. It explains edge cases like non-equivalent bet shapes and temporal misalignment, making behavior fully transparent. No contradiction with annotations.

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

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

The description is lengthy but information-dense and well-structured. It starts with purpose, then explains modes, response fields, and safety fields. Each sentence adds necessary context. Minor deduction for length, but it's justified given the tool's complexity.

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

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

The tool has no output schema, so the description must fully explain the response. It does so by detailing leg-by-leg prices, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. This covers all necessary information for correct invocation and interpretation, making it 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 all three parameters. The description adds significant value: it enumerates the 10 topic shortcuts, gives examples for explicit parameters, and explains how overriding works. This enriches the agent's understanding of parameter 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 clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison. The purpose is specific and unambiguous.

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

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

The description explains two modes (topic and explicit) and when to use each, including examples. It also warns that most pre-mapped topics return compatibility warnings, setting realistic expectations. It could be improved by explicitly stating when not to use this tool, but the guidance provided is strong.

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, destructiveHint. The description adds that it returns attribute rows and geometry, and mentions pagination via limit/offset. No contradictions. Could include more on return format or constraints, but sufficient.

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

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

Two sentences, no wasted words. The purpose and a key usage tip are front-loaded. Every sentence earns its place.

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

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

Given no output schema, the description mentions return type (attribute rows and geometry). It covers the essential context: source (search_datasets), parameters, and sample usage. No gaps for a data query 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 individual parameter descriptions. The description adds a practical tip for sampling but does not provide deeper semantics beyond what is already in the schema. No parameters are left undefined.

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 queries an ArcGIS Feature Service/Map Service layer by URL, using SQL-like parameters. It ties the tool to a workflow from search_datasets, distinguishing it from siblings like search_datasets (finding) and layer_info (metadata).

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

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

Provides a concrete usage example ('Use where="1=1" + out_fields="*" to sample.') and implies it should be used after search_datasets. However, it lacks explicit when-not-to-use or alternative tool mentions for similar tasks.

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: explains that omitting the key lists all keys, describes scoping to identifier, and provides examples of stored data (ticker, address, notes). 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?

Three sentences covering dual behavior, use cases/benefits, and scoping/pairing. No redundancy, front-loaded with primary action, every sentence earns its place.

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

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

Fully explains the tool's behavior, use cases, scoping, and relation to other tools. No output schema needed; return behavior is implied. Complete for a simple read-only retrieval/list 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 has 100% coverage explaining the key parameter. Description adds value by giving concrete examples of what keys might store and linking the tool to the broader save/retrieve/delete workflow. Exceeds 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?

Description clearly states the verb 'retrieve' and 'list', specifies the resource 'values saved via remember', and distinguishes from siblings by mentioning 'remember' and 'forget'. It explicitly tells what the tool does and how it differs from related tools.

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

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

Provides clear guidance on when to use: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget. Lacks explicit when-not-to-use, but the positive context is strong.

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

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

The description adds significant behavioral context beyond annotations (readOnlyHint, idempotentHint): it details return fields (source, citation_uri, raw payload), the effect of mark_read (flags events read so next call shows only newer ones), and that the feed is also accessible via REST endpoint. 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?

Five sentences, front-loaded with the core function, each sentence adds distinct information. No redundancy or fluff. Efficiently conveys purpose, usage, and context.

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 outlines return fields (source, citation_uri, raw payload) and mentions filtering and mark_read. Lacks explicit pagination details (limit is in schema) but is sufficient for a simple retrieval tool. The alternative endpoint and polling note add completeness.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining the purpose of mark_read (flag read for next call) and since (fired_at >= time), and mentions filtering possibilities. It does not repeat schema details but enriches understanding.

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

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

The description clearly states the tool pulls fired events from a subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload). It distinguishes from siblings like list_subscriptions (which lists subscriptions, not events) and subscribe (which creates subscriptions). The verb 'pull' and resource 'recent alerts' are precise.

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 guidance on filtering by type/since, using mark_read to track reading, and notes that polling works fine. Mentions an alternative endpoint (registry.pipeworx.io/alerts.json) for scripts/dashboards, implying when not to use the tool. However, lacks explicit when-not-to-use or direct comparison to sibling tools.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are present, and the description adds substantial behavioral detail: fan-out to multiple sources, GDELT→GNews fallback mechanism, USPTO soft-fail, date acceptance formats, and output structure. 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 dense paragraph but every sentence serves a purpose, front-loading example queries and covering all necessary aspects concisely 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?

Despite having no output schema, the description fully explains the return structure (changes[] grouped by source, total_changes count, citation URIs), documents fallback and soft-fail behaviors, and provides sufficient context for a complex multi-source tool.

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

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

Schema coverage is 100%, but the description enhances parameters with context: type is limited to 'company', since formats and typical usage ('Use 30d or 1m for typical monitoring'), value as ticker or CIK. Adds meaning 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 provides a change feed for a company over a time window, listing specific sources (SEC, GDELT→GNews, USPTO) and explicitly distinguishes from sibling tool entity_profile via 'Use entity_profile instead when you want the static profile.'

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

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

The description provides explicit usage examples ('What's new with X', 'latest on Y', etc.) and clearly states when to use the alternative tool entity_profile, offering both usage context and exclusion criteria.

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 idempotentHint=true and destructiveHint=false, which the description complements by adding scoping by identifier and TTL (persistent for authenticated, 24h for anonymous). It does not explicitly address overwrite behavior, but idempotency implies safe re-setting.

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

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

The description is two well-structured sentences, front-loading the purpose and followed by usage context. Every word adds value—no redundancy or filler.

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

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

For a simple key-value store with no output schema, the description covers purpose, usage, scoping, TTL, and pairing. It lacks explicit mention of overwrite behavior, but the idempotent hint and general description suffice for completeness.

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

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

Schema coverage is 100% with clear descriptions for key and value. The description enriches this with example keys and notes that value can be any text. This goes beyond the schema to aid the agent in parameter selection.

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

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

The description clearly states the tool saves data for later reuse, both within and across conversations. It distinguishes itself from siblings by explicitly pairing with recall and forget, ensuring the agent knows it's a storage operation with dedicated retrieval and deletion counterparts.

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

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

The description provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (ticker, address, preference). It also tells the agent to pair with recall and forget, effectively excluding alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by stating that each call cascades through multiple lookup endpoints internally, and specifies the exact return fields per entity type (including citation URIs). This goes beyond what annotations provide.

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

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

The description is well-structured, starting with natural language queries, then the core purpose, followed by detailed type breakdowns. It is front-loaded with the most important information. While slightly verbose in the type details, every sentence contributes useful information without 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?

Despite having no output schema, the description thoroughly explains what the tool returns for each entity type, including citation URIs and specific fields. It also sets expectations about internal processing (cascading lookups). Minor omissions like error handling or disambiguation of ambiguous inputs prevent a perfect score.

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 with descriptions for both parameters. The description further clarifies acceptable inputs for the 'value' parameter by giving examples per type (e.g., ticker, CIK, name for company; brand or generic name for drug). This additional nuance earns a score above the baseline of 3.

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

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

The description explicitly states the tool's purpose: resolving a user-spoken name to the official identifier needed by other tools. It provides concrete examples like 'What's the ticker for...' and directly addresses the core use case, clearly distinguishing it from sibling tools like entity_profile.

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

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

The description gives a clear directive to 'Use FIRST whenever you have a name but need an ID.' It also explains that using resolve_entity replaces 2-3 manual lookups, implying this tool is more efficient than alternatives. However, it lacks explicit guidance on when not to use it or mention of any edge cases.

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

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

The description adds behavioral context beyond annotations: it 'probes each entity with ai_visibility_check', 'ranks by score', and 'surfaces which is most/least recognized'. It also mentions returning a ranked list with score, confidence, signal density. Annotations already declare readOnlyHint, openWorldHint, idempotentHint; 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 three sentences, each carrying essential information. It is front-loaded with the main purpose, then details behavior, then usage context. 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?

Given 4 parameters, 4 annotations, and no output schema, the description adequately explains the tool's operation and output format (ranked list with score/confidence/signal density). It lacks explicit mention of pagination or error handling, but for a comparison tool this 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?

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning: 'First entry treated as the subject for narrative; rest are competitors.' It also explains the relation between `models` and `_apiKey`. This goes beyond what the schema provides.

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

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

The description clearly states the tool 'compares AI visibility across multiple entities side-by-side'. The verb 'compare' and resource 'AI visibility' are specific. It distinguishes from sibling `ai_visibility_check` (single entity) and `compare_entities` by focusing on AI presence and using that tool as a sub-step.

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 'useful for competitive AI-marketing audits' and provides an example question. It implies usage for comparing 2-8 entities. However, it does not explicitly state when not to use or mention alternatives like `ai_visibility_check` for single entities.

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, idempotentHint, etc.), description details that it fans out to two services, returns a summary block with specific fields, per-advisory detail, links, alternatives. It warns about potential partial failures and timeout behavior (5-30s for bundlephobia first measurement).

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 about 4 sentences, front-loaded with purpose, followed by usage, then limitations and behavior. 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?

Despite no output schema, description thoroughly explains what is returned (summary block, per-advisory detail, links, alternative versions), handles partial failures gracefully, and states ecosystem scope. This is complete for a 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% and both parameters are well-described. Description adds extra context for package: 'Scoped packages (e.g. '@types/node') are accepted.' This slightly exceeds schema description, earning a 4.

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

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

Description clearly states it's a composite check for npm packages, specifying the sources (deps.dev, bundlephobia) and the question it answers. It distinguishes from siblings by mentioning NPM-only scope and that other ecosystems use different 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: when an agent asks about safety, popularity, size, or cost of adding a package. Also provides explicit exclusion: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly.'

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds that the tool returns specific fields and a url for downstream use, 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?

Two sentences, front-loaded with action and scope, no wasted words. Every sentence adds value, including the downstream usage instruction.

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 clearly lists return fields and provides context for further use. Annotations cover safety. All optional parameters are explained. Complete for a search 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 clear descriptions for all three parameters (limit, query, org_id). The description reinforces the 'by keyword' aspect and adds example keywords, but adds minimal 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 clearly states the tool searches Delaware County GIS datasets by keyword, lists example datasets, and explains the return fields including a url for use with query_layer/layer_info, distinguishing it from those sibling tools.

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

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

Provides clear context: search by keyword, then pass the returned url to query_layer/layer_info. Does not explicitly exclude scenarios or mention alternatives, but the instruction is direct 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?

Discloses internal details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag, and return of offsets/scores. Adds value beyond annotations which already mark safe traits.

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

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

Description is concise, front-loaded with core function, and every sentence adds new, non-redundant information. 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?

Given no output schema, the description explains return format (passages, offsets, scores) and truncation behavior. All parameters are covered, and the usage context is fully addressed without missing aspects.

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 contextual examples for query parameter and clarifies the text parameter's cap. No new semantics beyond schema, but enhances understanding. Baseline 3, bumped to 4 for helpful examples.

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 does semantic search inside a fetched record, using specific verbs and resources. It distinguishes from siblings like ask_pipeworx_grounded, making the purpose immediate.

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 to use when records are too large for prompts, and directly pairs with ask_pipeworx_grounded for grounding. Provides clear when-to-use and alternative.

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 the tool is not read-only, is idempotent, and not destructive. The description adds context beyond annotations by stating requirements (OAuth account), delivery constraints (SMS 10/day cap, webhook auto-disable after 10 failures), and that webhook signing secret is returned once. This provides valuable behavioral guidance.

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 fairly long but well-structured, starting with the core purpose, then detailing types and delivery options. While every sentence adds value, some redundancy exists (e.g., delivery details repeated). It could be slightly more concise 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?

Given the tool's complexity (nested objects, 3 parameters, no output schema), the description is comprehensive. It covers all input parameters, explains return value (subscription id), describes always-on feed channel, and details optional delivery channels with constraints. No gaps are apparent.

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 description coverage, baseline is 3. The description adds extensive meaning beyond the schema, including example values for each subscription type's params (e.g., items codes for sec_8k, min_spread_bps for polymarket_edge) and detailed constraints for delivery channels (verification, rate limits, webhook HMAC signing). This significantly aids correct parameter usage.

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: creating a subscription to a live-data event stream and returning the subscription ID. It explicitly lists supported types and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 when to use the tool (proactive monitoring) and specifies prerequisites (Pipeworx OAuth account). It also details supported types and delivery channels, providing clear context for usage. However, it could be more explicit about when not to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior. The description adds that the tool returns categorized examples and tool shapes, which is useful. However, it does not mention potential response size or pagination, but for an onboarding tool this is sufficient.

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

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

The description is somewhat long but well-structured with a dash and front-loaded trigger phrases. Every sentence earns its place, though it could be slightly more concise by trimming the explicit topic list.

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), the description covers all relevant aspects: purpose, trigger phrases, return structure, parameter usage, and place in the tool ecosystem. It is complete for an onboarding tool.

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

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

The schema coverage is 100% for one parameter. The description adds value by listing example topic values (finance, pharma, etc.) and explaining the effect of omitting topic (cross-category spread). This goes beyond the schema's minimal 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's purpose as an onboarding entry point for understanding what Pipeworx can answer. It provides multiple trigger phrases and explains the return structure (category-bucketed example questions with tool+argument shapes). This distinguishes it from sibling tools like ask_pipeworx or deep_research.

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

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

The description explicitly says to use this tool FIRST when the agent doesn't know what Pipeworx can do. It gives guidance on calling with no arguments for full spread or passing a topic for focus. This provides clear when-to-use and context.

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

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

Annotations already indicate non-readOnly (write), non-destructive, and idempotent. The description adds context about ownership enforcement and deactivation vs deletion, aligning with annotations. No contradictions; additional behavioral detail enhances transparency.

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 covering purpose, ownership, and behavioral nuance. No wasted words; information is front-loaded.

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

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

For a single-parameter tool with no output schema, the description provides essential context: ownership, deactivation semantics, and historical availability. Complements annotations well, leaving no critical gaps.

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

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

Schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description only repeats 'by id' and the source, adding minimal value. With 100% schema coverage, 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 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from siblings like 'subscribe' (create) and 'list_subscriptions' by noting ownership enforcement and deactivation behavior, making purpose unambiguous.

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

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

The description implies when to use (to cancel own subscription) and mentions ownership constraint. It references 'recent_alerts' for historical data, providing some guidance, but lacks explicit when-not-to-use or direct alternatives beyond that.

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 detail beyond annotations: returns a verdict (with types), extracted structured form, actual value with citation, and percent delta. Also notes efficiency improvement over multiple calls. 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?

Front-loaded with examples, then purpose, then details. All sentences serve a purpose (examples, domain, outputs, efficiency). Slightly long but each part is informative, not redundant.

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

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

With one parameter well-documented, detailed output description, and annotations, the tool is fully specified. No missing critical information for an 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 covers claim parameter with description. Description provides example claim strings and context about the type of claims (company-financial). This adds meaning beyond schema, though schema already has decent coverage. Baseline 3, increased due to useful context.

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

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

Description clearly states it performs natural-language claim verification against authoritative sources, specifically company-financial claims. While it doesn't explicitly contrast with sibling tools, its unique function (fact-checking claims) makes it distinct. The verb 'verify' and resource 'authoritative sources' 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?

Describes when to use: 'whenever the agent needs to check whether something a user said is factually correct.' Also specifies domain limitation to company-financial claims for public US companies, which implicitly guides when not to use. Clear but could explicitly state exclusions.

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