Data Dc

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 valuable context: it probes multiple models, returns per-model results with raw_response, and notes cost implications (free vs BYO). 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 with no wasted words. The description starts with the core action and output, then provides usage details. Every sentence adds value.

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

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

No output schema exists, but the description explains the return structure (per-model {score, confidence, signals, raw_response} + combined view). It also covers use cases and parameter behavior, making it sufficient for a tool of moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining what entity types to use (brand, product, topic), how models selection works with _apiKey dependency, and context usage for disambiguation. This goes 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 probes LLMs for knowledge about an entity and provides a visibility score (0-100). It specifies the verb 'probe', the resource 'LLMs', and the output 'score visibility', distinguishing it from sibling tools like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains when to pass _apiKey for Anthropic vs using the free default. It lacks explicit when-not-to-use guidance but is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, setting a high baseline. The description adds valuable context: the tool routes to 4,552 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with a single fast call. This goes beyond annotations without contradicting them.

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

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

The description is relatively long but every sentence serves a purpose: stating preference over web search, listing supported data types, explaining routing, giving trigger phrases, and contrasting with siblings. It is front-loaded with the key instruction 'PREFER OVER WEB SEARCH'. 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?

Despite lacking an output schema, the description sufficiently explains return behavior: structured answer with pipeworx:// citation URIs. It covers a wide range of question types and domains, and positions the tool as the default entry point. No gaps remain for an AI agent to understand what to expect.

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

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

Schema description coverage is 100%, so the schema already documents the parameter. The description adds aliases (q, text, input, query, prompt) and provides example questions, which adds some value but does not fundamentally change parameter meaning. Meets baseline with minor enhancement.

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: routing factual questions to 4,552 verified sources and returning structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded (for hallucination-resistant single answers) and deep_research (for broad multi-part queries), and from web search, making the purpose unambiguous.

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

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

Explicitly states when to prefer this tool over web search and siblings, provides trigger phrases ('what is', 'look up', 'find', etc.), and gives examples. It also specifies when to step up to alternatives (ask_pipeworx_grounded for confident single answers, deep_research for broad questions), offering clear usage guidance.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description details the extra LLM call cost, exact refusal reasons, and the guarantee that answers come only from tool results. This adds significant behavioral context.

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

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

Front-loaded with the core purpose, then logically explains routing, extraction mechanism, refusal reasons, and usage trade-off. Every sentence is informative and earns its place despite 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?

Given the complexity (routing, extraction, refusal, cost), the description covers return format, success/failure modes, and when to use. No output schema needed as return fields are described.

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

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

The input schema has 6 aliases for the same parameter 'question', all described as 'alias for question.' The description does not add constraints or format details beyond what the schema provides, though it implies the question is used for routing. 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 it is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes itself from the sibling tool ask_pipeworx by the extraction behavior and refusal reasons.

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 whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides a cost trade-off: 'prefer ask_pipeworx for casual lookups.' Names the alternative and usage conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavior: market resolution, classification, parallel fan-out, response shapes, resolver contract (confidence, score, alternatives), parent event extraction, news fallback mechanisms, safety short-circuits, wide-spread handling, and cancellation rule parsing. 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 well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) and uses bold headers for readability. However, it is lengthy and could be more concise by trimming some verbose examples (e.g., detailed fan-out lists). Still, it remains organized and each section adds value.

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

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

Even without an output schema, the description thoroughly covers all return values (market, analysis, evidence, resolver, parent_event, news fields) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It 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 coverage is 100%, but the description adds significant meaning: explains depth (quick vs thorough), market input (slug, URL, question), and include_raw (summarized vs full payloads). Gives examples and trade-offs, going well beyond the schema's basic descriptions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). The name 'bet_research' and purpose distinguish 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 states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains when to inspect confidence fields and handling of closed/illiquid markets. However, it does not explicitly mention when NOT to use or list alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description is not required to repeat those. However, the description adds valuable behavioral context: it explains that for type='company', it pulls LATEST 10-K revenue, net income, cash, long-term debt from SEC EDGAR/XBRL with correct off-calendar fiscal year handling; for type='drug', it pulls FAERS adverse-event counts, FDA approval counts, active trial counts. It also mentions results are sorted by primary metric and returns citation URIs. This goes 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 moderately long but every sentence adds value: it starts with example queries, then explains functionality, data sources, sorting, and return format. It is well-structured and front-loaded with the most important information. No filler sentences.

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

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

Given there is no output schema, the description does a good job explaining what the tool returns (paired data with citation URIs, sorted by primary metric). It also covers data sources and edge cases (off-calendar fiscal years). For a tool with only two parameters and straightforward functionality, this is sufficiently complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant meaning: it provides examples of valid values (tickers/CIKs for company, names for drug), clarifies min/max items (2–5), and explains what data is returned for each type. This adds context beyond the schema.

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

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

The description clearly states the tool does side-by-side comparison of 2–5 companies or drugs in one parallel call. It explicitly mentions it should be preferred over sequential single-pack lookups, distinguishing it from sibling tools like entity_profile. The examples of queries ('Compare X and Y', 'X vs Y', etc.) make the purpose immediately understandable.

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

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

The description provides explicit guidance on when to use the tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and gives concrete examples of queries that trigger it. It does not explicitly state when not to use it (e.g., for a single entity), but the context is clear. It could be improved by referencing the sibling tool 'entity_profile' explicitly.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds the return format (layer id + name) and intended use with dc_query, providing modest additional 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?

Three sentences, front-loaded with purpose, no redundant information. Every sentence contributes meaning.

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

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

For a simple tool with one optional parameter, no output schema, and comprehensive annotations, the description covers purpose, usage, examples, and return format completely.

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

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

Schema coverage is 100% and includes description of the service parameter. The description adds concrete examples (crime, service_requests, permits) and clarifies behavior when omitted, adding marginal value above the schema.

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

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

The description clearly states the verb 'list', the resource 'layers of a Washington, DC ArcGIS service', and the purpose 'for discovery'. It distinguishes from sibling tools like dc_query and dc_recent by focusing on layer discovery.

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

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

Provides explicit usage instructions: pass a short name or full ArcGIS service path, or omit to list known services. While it does not include negative guidance, the context is clear enough for correct invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about epoch date conversion to ISO and default/max limit, enhancing behavioral understanding 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?

Three sentences, front-loaded with purpose, no wasted words. Highly concise and structured effectively.

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 provides necessary context: query capabilities, epoch date handling, and integration with sibling tools. Complete for this tool's complexity.

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

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

Schema coverage is 100% with all six parameters described. The description doesn't add new parameter-level meaning beyond what schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool queries DC ArcGIS layers, specifies inputs (service path + layer id), and mentions full ArcGIS query parameters. It distinguishes from siblings by referencing dc_layers and dc_recent.

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

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

Explicit guidance provided: use this tool to query any layer, and use dc_layers or dc_recent to discover services/layers. This tells the agent when to use this vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is covered. Description adds useful behavioral context beyond annotations: 'Returns the latest rows (newest-first), with ArcGIS epoch dates converted to ISO.' No contradictions found.

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

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

Description is 4 sentences, front-loaded with purpose and key usage hints. Every sentence adds value: purpose, preference guidance, dataset names, behavior details, and filtering advice. No fluff or repetition.

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

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

With 3 parameters, no output schema, and high schema coverage, the description covers purpose, usage context, filtering, and links to sibling tools. It is sufficient for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by naming the enum values (crime, 311, permits) and giving an example of the 'where' parameter syntax. This goes beyond the schema's description, especially for the 'where' field which benefits from the SQL example.

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 'Recent records from a common Washington, DC open dataset' with specific verb 'get recent records' and resource 'opendata.dc.gov / ArcGIS'. It distinguishes itself from sibling tools by emphasizing 'no service ids needed' and explicitly names three datasets (crime, 311, permits).

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 'PREFER OVER WEB SEARCH' for specific queries and provides guidance on when to use alternatives: 'for other layers use dc_layers + dc_query'. This gives clear context on when to use this tool versus siblings.

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

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

Annotations already mark it read-only, open-world, idempotent, non-destructive. Description adds account requirements, paid tiers, parallel decomposition, return format with evidence and gaps, and expected 15-60s runtime—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?

Long but every sentence adds value; front-loaded with critical account/fallback info, well-structured. Minor redundancy but overall 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 complexity (parallel research, no output schema), description fully covers prerequisites, time, return format, examples, and limitations. No gaps for agent decision-making.

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

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

Schema covers 100% of parameters with clear descriptions. Description adds further context: depth corresponds to facet count, question decomposition is intentional.

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

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

The description clearly states it performs 'grounded multi-source research' across structured data with parallel tool calls, distinguishing it from open-web search and explicitly contrasting with sibling ask_pipeworx.

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

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

Explicitly tells when to use (broad/multi-part questions over structured data) and when not (single lookup, breaking news), naming alternatives and reasons.

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

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

Annotations already indicate safe read (readOnlyHint=true, destructiveHint=false, idempotentHint=true). Description adds that it returns top-N relevant tools with full schemas and examples, ready to call directly — 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?

Description is fairly concise given the amount of information. Front-loads purpose and usage. Slightly long but every sentence provides value.

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

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

No output schema exists, but description fully explains return format: top-N tools with names, descriptions, and full input schemas. Parameters fully covered. Complete for a discovery 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 detailed descriptions. Description adds examples and clarifies aliases for query parameter, and explains limit default and max. Adds value beyond schema.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and explicitly differentiates from siblings by saying 'Call this FIRST when you have many tools available and want to see the option set'.

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

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

Explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST...'. No explicit when-not-to-use, but strong positive guidance suffices.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds critical context: the USPTO PatentsView API is noted as sunsetting May 2025 with a soft-fail behavior, and the data return structure is detailed. There is no contradiction with annotations—this description enriches the agent's understanding of what happens during execution.

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

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

The description is thorough and front-loaded with example queries, but it is somewhat long. Every sentence adds value, so no wasted words, but a slightly tighter structure might improve scanning. Still, clarity outweighs conciseness here, so a 4 is appropriate.

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

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

Given the complexity of the tool and the absence of an output schema, the description is remarkably complete. It lists all return items (CIK, company_name, recent_filings with URIs, fundamentals, patents, news, LEI), mentions the patents soft-fail limitation, and explains input constraints. The agent can fully understand what the tool does and what it returns without needing an output schema.

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

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

The schema already provides 100% coverage with descriptions for 'type' and 'value', but the description adds significant value: it explains that 'type' is currently limited to 'company', clarifies that 'value' can be a ticker or zero-padded CIK, and explicitly states that names are not supported. This goes beyond the schema to shape correct 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 produces a 'full cross-source profile of a US public company in ONE parallel call', enumerating specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. It uses concrete example queries like 'Tell me about X' and distinguishes itself from sibling tools like resolve_entity by noting that names are not supported and that tool should be used first if only a name is available.

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 advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing a clear when-to-use directive. It also tells the agent exactly when to use resolve_entity as an alternative ('Names not supported — use resolve_entity first if you only have a name'), making the usage boundaries unambiguous.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description reinforces the delete action and adds 'clear sensitive data' context but does not disclose idempotency (annotations cover it) or behavior on missing keys. Minimal extra value beyond annotations.

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

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

Two concise sentences: first states the action, second provides usage context and pairing. No fluff, front-loaded, each sentence earns its place.

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

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

For a simple single-parameter delete tool with annotations, the description covers purpose, usage guidance, and relationships. Does not specify behavior on missing key or error handling, but overall adequate for agent use.

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

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

Only parameter 'key' is covered in schema (description: 'Memory key to delete'). The description mentions 'by key' but adds no new semantic detail beyond the schema. With 100% schema coverage, baseline is 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 starts with 'Delete a previously stored memory by key', clearly stating the action (delete), resource (memory), and method (by key). It distinguishes from siblings by naming 'remember' and 'recall' for different operations.

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

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

Explicitly provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with remember and recall. No explicit when-not or alternatives, but context is clear.

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

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

Annotations indicate a safe, idempotent read operation. The description adds detail: it fetches the page, extracts title/description/key links, and emits markdown output. No contradictions with annotations.

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

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

Two succinct sentences plus a bullet list of use cases. Every sentence is informative, front-loaded with purpose.

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

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

With no output schema, the description adequately explains output as a single text blob ready for deployment. It covers the process and use cases sufficiently for a simple 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 the baseline is 3. The description does not add meaning beyond the schema; it mentions max_links default but schema already specifies that.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying it fetches the page and extracts title/description/key links. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description provides explicit use cases: indexing a client's site, drafting for own project, auditing competitor AI presence. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already indicate non-destructive, read-only, idempotent; description adds detail on return fields and the effect of the include_inactive parameter, enhancing 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 front-load purpose and return fields, followed by usage guidance. No unnecessary words.

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

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

Simple tool with one optional parameter; description lists return fields, fulfilling need without output schema. Could mention pagination or error handling, but not critical.

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

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

Schema covers the sole parameter with description, so baseline 3. Description does not add extra parameter meaning beyond what 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?

Clearly states it lists the caller's active subscriptions and names specific return fields, making the purpose unambiguous.

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

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

Provides explicit use cases: review subscriptions before adding more or find an id to cancel. Implicitly distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Annotations are all false, so description carries full burden. Description adds key behavioral traits: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that team reads digests daily affecting roadmap. This goes beyond basic 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, front-loaded with main action, no wasted words. Structure is clear and 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 3 params (2 required), nested object, and no output schema, description covers usage, constraints, and param guidance. Lacks detail on post-submission behavior (e.g., acknowledgment), but sufficient for a simple feedback tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description reinforces enum values and adds context on how to describe issues ('in terms of Pipeworx tools/packs'). Adds value beyond schema.

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

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

Description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb ('tell') and resource ('Pipeworx team/feedback'), and distinguishes it from sibling tools which are query/research 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: bug, feature/data_gap, praise. Also provides guidance on what not to do ('don't paste the end-user's prompt') and mentions rate limits and quota. Does not explicitly compare to sibling tools but context makes it clear this is the only feedback 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, caching window (5min-1h). 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?

Concise, front-loaded with main purpose, structured with bullet-like list of use cases. Every sentence adds value.

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

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

No output schema, but description adequately explains return format (top tools, packs, call volume) and data nature (count tuples). Parameter is optional and fully documented. Complete 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 100% (baseline 3). Description adds semantic value by explaining window enum implications: shorter windows for hot items, longer for steady-state demand.

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 returns top tools, top packs, total call volume over recent windows. Verbs 'Returns' and specific resource 'top tools, top packs, total call volume' make 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?

Explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use case) and caching behavior. Lacks explicit when-not-to-use but clearly differentiates from siblings via trending focus.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: explains the algorithms (monotonicity checks, partition sum), edge cases (semantic anchor, partition filter, fill check), and limitations (thin legs, placeholder filters). 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 quite long and detailed, which is justified by the tool's complexity. However, it could be more concise while retaining key information. The structure is logical but front-loading could be improved; the core purpose is stated first, but details like the fill check could be summarized more briefly.

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, the absence of an output schema, and the richness of the annotations, the description covers all necessary aspects: input modes, internal logic, response structure, fill check limitations, and cross-references to related tools. It leaves no obvious gaps for an agent to use the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant meaning beyond the schema by explaining what each mode does internally, providing example slugs, and detailing behavior when no args are given. This enriches the agent's understanding beyond the schema's basic field descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'. It distinguishes between modes (no args, event, topic) and explains what each does, effectively differentiating it from sibling tools by specifying the unique method used.

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 for each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also warns when not to trade (when fill_check shows realizable_edge_pp <= 0) and references a sibling tool (polymarket_fill_risk) for custom sizing, offering clear decision points.

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

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

The description extensively details the internal models, caching behavior (1h KV cache), response segments, diagnostics, and edge metrics. This adds significant value beyond the annotations (readOnlyHint, idempotentHint, etc.), which only declare safety properties.

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

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

The description is comprehensive but verbose, with multiple paragraphs. While it front-loads the purpose effectively, some sections (e.g., detailed model formulas) could be condensed 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 complexity (9 parameters, no output schema, nested response), the description covers all aspects: output structure, model families, filters, caching, and diagnostics. It is fully sufficient for an agent to use the tool correctly.

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

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

The input schema covers 100% of parameters with descriptive text. The tool description does not add additional meaning beyond what the schema already provides, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx disagreement.

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

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

The description provides clear context for when to use the tool (e.g., 'what should I bet on today') and explains tradeable-edge knobs and Fed bet handling. However, it does not explicitly state when not to use it or mention alternatives.

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

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

The description adds significant behavioral context beyond annotations: it details the response structure (tracked, expired, snapshot_dates), explains that snapshots are written on cache-miss and gaps indicate no scan, clarifies that decay is from daily closes not intraday, and notes the 60-day TTL. Annotations already indicate read-only and idempotent, and the description is consistent with them.

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

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

The description is front-loaded with the purpose and structured into clear sections: purpose, response details, and limits. It is somewhat verbose but every sentence adds value. Could be slightly tighter, but overall 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?

Without an output schema, the description fully explains the return value structure (tracked, expired, snapshot_dates) including key fields like trend, decay_pp_per_day, lifespan_days, and snapshot_dates. It also covers limits and data sources, making it complete for the tool's functionality.

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 described. The description adds meaning by explaining the default values (days=14, max 30; window='1wk'), the purpose of 'days' as lookback, and 'window' as snapshot family. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on temporal behavior rather than raw snapshot data.

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 explains the use case: comparing fresh vs old edges and understanding decay. It also provides limits on history depth and data source. However, it does not mention when to use alternatives like polymarket_edges or polymarket_arbitrage, so it lacks explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds context beyond annotations by detailing what the tool walks (the ladder), what it returns (top_of_book, vwap_fill_price, slippage_pp, etc.), and the verdict categories. 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 relatively long but well-structured with mode explanations and enumerated return fields. Every sentence carries substantive information, such as the warning about forced_directional_risk. Could be slightly more concise but remains clear.

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

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

No output schema exists; the description compensates by fully explaining return values for both single-market and basket modes, including edge cases like thin legs and forced_directional_risk. It covers all necessary context for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% for all 4 parameters. The description reinforces parameter meanings (e.g., size_usd interpretation differs by mode), adds default values and clamping ranges, and clarifies when to use market vs event. This adds value beyond the schema's brief descriptions.

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

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

The description explicitly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes: single-market and basket/partition. It uses specific verbs like 'check' and 'walks the ladder,' and differentiates from siblings by recommending use before 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 provides clear when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale, including that theoretical overround on thin books is not capturable and partial basket fills create unhedged directional risk.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds context about compatibility_warning fields, temporal alignment, and skipped cross types, disclosing that not all pairs yield spreads. 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 verbose and could be condensed. While well-structured with clear sections (modes, response fields, safety fields), it includes redundant elaboration (e.g., repeated warning about pre-mapped shortcuts). Some details belong in schema or separate docs.

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

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

Despite lacking an output schema, the description thoroughly explains response structure (leg prices, top_spreads_pp, safety fields) and covers edge cases like compatibility_warning and temporal misalignment, making the tool's behavior fully predictable.

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 description adds significant value by explaining the two operating modes, how overrides work, and listing all available topics for the `topic` parameter. This goes beyond the schema's property descriptions.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same question, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on inter-market comparison.

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

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

Explicitly explains two modes (topic shortcuts vs. explicit tickers) and when to use each. Warns that most pre-mapped topics return compatibility_warning, guiding against false expectations. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, non-destructive, idempotent. Description adds scope details (anonymous IP, BYO key hash, account ID) and that omitting key lists all.

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 that pack all necessary information without any fluff.

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

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

For a simple tool with one optional parameter and good annotations, the description fully explains its purpose, usage, and relationship to siblings.

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 the key parameter at 100%. Description adds that omitting it lists all keys, which is crucial functional nuance beyond the schema.

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

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

The description clearly states it retrieves a saved value or lists all keys, distinguishing it from siblings like 'remember' and 'forget'.

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

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

Explicitly says when to use (look up stored context) and how it pairs with remember/forget, providing clear context for the agent.

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

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

Annotations already indicate read-only and idempotent behavior, but the description adds context: each event carries source, citation_uri, payload; mark_read side effect; filtering capabilities. 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 concise, front-loaded with purpose, then details on return values and filtering. Every sentence adds value; 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 what is returned. It covers key behaviors (filtering, marking read, polling) but omits limit behavior and edge cases. Still sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the effect of mark_read and providing an example for type filtering. It compensates beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed, specifying what is returned (source, citation_uri, payload). It is specific but does not explicitly differentiate from sibling tools like recent_changes or dc_recent.

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

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

The description implies usage for retrieving recent alerts with optional filtering and marking read, but it does not provide guidance on when to use this tool versus alternatives. Mentioning polling and an alternative endpoint is helpful but not a substitute for explicit usage guidelines.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: parallel fan-out to multiple sources, GDELT preference with automatic fallback to GNews, USPTO soft-failure, and date format specifics. 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 thorough but not overly verbose. It front-loads with query examples, then methodically explains sources, parameters, and fallbacks. Every sentence contributes value. A slight trim could improve conciseness, but it remains well-structured and 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 the tool's complexity (multiple data sources, fallback logic, date formatting, no output schema), the description is remarkably complete. It covers input format, source behavior, special cases (USPTO sunset), and return shape (grouped changes, total count, URIs). No gaps remain for effective agent use.

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

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

Schema already describes each parameter with 100% coverage. The description adds critical nuance: `since` accepts ISO or relative shorthand (e.g., '7d', '3m'), recommends '30d' or '1m'; `value` accepts ticker or CIK; `type` is only 'company'. This goes beyond the schema's basic descriptions, helping agents format inputs correctly.

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

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

The description clearly states it provides a change feed for a company over a window, listing specific sources (SEC EDGAR, GDELT→GNews, USPTO) and return structure. It also distinguishes from the sibling entity_profile for static profile, 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 provides multiple example queries, explicitly states when to use entity_profile instead, explains fallback behavior (GDELT→GNews on rate-limit/5xx, USPTO soft-fail), and recommends typical `since` values like '30d'. This gives agents clear decision logic for when and how to invoke.

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

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

Annotations provide idempotentHint=true. Description adds persistence details (authenticated vs anonymous, 24-hour retention) and scoping by identifier, but does not mention any potential limitations like key uniqueness or overwrite 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?

Three sentences, front-loaded with purpose and usage, no filler. Every sentence adds value.

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

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

With 2 params, no output schema, and good annotations, description covers purpose, usage, behavioral traits (persistence), and sibling relationships fully.

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 description need not add much. Description mentions 'key-value pair' but does not add semantic detail beyond schema examples; baseline score 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 explicitly states 'save data' with specific resource 'data the agent will need to reuse later'. Clearly distinguishes from sibling tools recall and forget.

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

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

Provides explicit when-to-use guidance ('when you discover something worth carrying forward'), mentions pairing with recall and forget, and differentiates from looking up again.

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

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

Adds significant context beyond annotations: explains internal cascading through multiple lookup endpoints and specifies return fields (ticker, CIK, company_name, citation URIs). This helps the agent understand tool behavior and output format.

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 example queries, every sentence is informative, and the structure is clear and concise. 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?

Covers all aspects: inputs, types, return values, citation URIs, internal process, and usage guidance. Despite no output schema, the description sufficiently explains what the tool returns, making it complete for decision-making.

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 provides enum and descriptions for both parameters (100% coverage). Description adds useful context like auto-disambiguation and exact return formats for each type, but baseline is already adequate.

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 resolves names to canonical IDs, with specific verb 'resolve' and resource types. It distinguishes itself from siblings by stating 'Use FIRST whenever you have a name but need an ID,' implying it is the go-to for name-to-ID mapping before other tools.

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

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

Explicitly says when to use ('Use FIRST whenever you have a name but need an ID') and provides example phrasings. However, it does not explicitly state when not to use or list alternative tools for different contexts, though it is implied.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds specifics: probes each entity with ai_visibility_check, ranks by score, returns score/confidence/signal density. It also discloses the optional Anthropic API key requirement for certain models.

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

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

Four sentences, each earning its place: action, mechanism, use case, output. Front-loaded with main purpose, no filler.

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

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

Given moderate complexity (4 params, no output schema), the description covers purpose, mechanism, output format (ranked list with metrics), and use case. It lacks mention of error handling or rate limits, but is sufficient for typical usage.

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

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

Schema coverage is 100%. The description adds value beyond schema: clarifies that entities are 'your brand + N competitors', first entry is subject for narrative, and that 'workers-ai' is the default model. This enriches understanding of 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 compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It distinguishes from the sibling ai_visibility_check (single entity) by focusing on comparison.

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

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

The description explicitly states the tool is useful for competitive AI-marketing audits with a concrete example. It implies ai_visibility_check for single-entity checks, but does not provide explicit when-not-to-use or alternatives beyond the example.

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

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

Describes partial failure behavior, timeouts (5-30s for bundlephobia), and that sources_failed will list failures. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Front-loaded with purpose, then detailed behavioral info. Slightly verbose but every sentence adds value. Could tighten minor 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 fields (summary block, per-advisory detail, links, recent versions) and handles edge cases (timeouts, sources_failed). Covers all necessary context for a complex 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%, but description adds value by explaining parameter semantics: scoped packages accepted for 'package', and 'version' defaults to latest. Also explains the composite output.

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 a composite check for npm packages using deps.dev and bundlephobia, answering questions about safety, popularity, and size. It distinguishes from sibling tools by specifying the npm ecosystem and the composite nature.

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

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

Explicitly tells when to use ('is X safe / popular / small') and when not to (PyPI/Maven/Cargo/Go), directing to alternative tools like deps.dev:version. Also notes scope limitations and graceful degradation.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds critical behavioral details: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, and has a 200K char cap with truncation flagging.

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

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

The description is a single, well-structured paragraph. Every sentence adds value: core purpose, usage context, return details, technical parameters, and limits. No redundant information.

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

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

Given the tool's complexity and lack of output schema, the description is thorough. It covers the embedding approach, windowing, character offsets, truncation, and pairing recommendations, making it fully actionable for an agent.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the meaning of 'text' (document to search), 'query' (natural-language with examples), and 'limit' (max passages). It also clarifies technical constraints like max chars.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It distinguishes itself from siblings by mentioning pairing with ask_pipeworx_grounded and specifying it's for when the record is too large for the prompt.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and provides context on how it pairs with another tool. It lacks explicit when-not-to-use statements, but the guidance is clear enough.

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: authentication requirement, creation of a persistent feed, delivery behavior (auto-disable after 10 failures). Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are consistent and the description complements them without contradiction.

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

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

The description is relatively long but well-structured: purpose, requirements, type examples, delivery options. Front-loaded with the overall action. Every sentence provides value, though a slight trimming could improve conciseness.

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

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

The tool has 3 parameters with nested objects, multiple subscription types, and delivery options. The description covers authentication, type-specific filters, delivery constraints, and return value (subscription id). No output schema exists, but the description mentions the return. It is complete given the complexity.

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

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

Despite 100% schema coverage, the description provides concrete examples and explanations for each parameter (e.g., sec_8k items codes, polymarket_edge topic, webhook signing details). This adds substantial meaning beyond the schema.

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

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

The description starts with a clear verb and resource: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the result (returns subscription id) and distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by stating it creates a persistent subscription.

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 requirement: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' Also details delivery channels with constraints (SMS cap, webhook auto-disable). However, it does not explicitly contrast with alternative tools for pulling alerts (recent_alerts) or for listing subscriptions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds behavioral context about returning example questions with tool+argument shapes, which is useful but not critical beyond annotations.

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

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

The description is fairly long but each sentence adds value. It is front-loaded with common query variations and structured with a clear info flow. Could be slightly more concise but not overly verbose.

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 (1 optional param, no output schema, rich annotations), the description fully covers purpose, usage, parameter, and output. No gaps for an agent to understand when and how to use it.

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

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

Schema coverage is 100% for the single optional parameter. The description enriches the schema by listing valid topic values (finance, pharma, etc.) and explaining the effect of omitting or specifying the parameter.

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

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

The description clearly states the tool is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs and distinguishes from siblings by referencing meta-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 ('Use this FIRST when you do not yet know what Pipeworx can do'), provides alternatives (meta-tools), and explains argument options ('Call with no arguments for full spread, or pass topic to focus').

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 deactivation (not deletion) and preservation of historical events, adding value beyond annotations (which include idempotentHint=true, destructiveHint=false). 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 concise sentences: first presents core action, second adds ownership and behavioral detail. 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?

Covers purpose, ownership, effect on data. No output schema needed. Missing mention of idempotency (covered by annotations). Adequate for a simple single-parameter 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 100% with clear id parameter description. Description adds ownership context but does not elaborate on parameter format or constraints 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?

Verb 'cancel' targets 'subscription by id', explicitly states deactivation vs deletion, and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Clearly states ownership enforcement (can only cancel own subscriptions), providing implicit context for when to use. No explicit alternatives mentioned, but 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds return format details (verdict values, structured form, citation, delta) and notes it replaces multiple calls. This supplements the annotations well without contradiction.

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

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

The description is moderately concise, front-loading trigger phrases and purpose. Each sentence adds value, though it could be slightly more streamlined without losing 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 thoroughly covers return values (verdict types, structure, citation, delta) and explains the replacement of multiple calls. It fully addresses the tool's complexity and use case.

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

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

Schema description coverage is 100% for the single 'claim' parameter. The schema already describes it as a natural-language factual claim. The overall tool description provides context but does not add extra meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description explicitly lists natural-language triggers, defines the tool as claim verification against authoritative sources, and specifies the domain (company-financial claims via SEC EDGAR + XBRL). This clearly distinguishes it from all sibling tools, with a specific verb and resource.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and notes the scope (company-financial, public US companies). It implies when not to use (non-financial claims) but lacks an explicit exclusion statement. Still provides clear context.

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