Data Dc

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

The description adds behavioral details beyond annotations: default model is free, Anthropic requires BYO key (direct payment), and describes return format (per-model fields + combined view). Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and description aligns with these.

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, efficiently front-loaded with the main purpose, no redundant words. Every sentence adds value.

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

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

Given four parameters, no output schema, and rich annotations, the description fully covers return structure, model options, cost implications, and typical use cases. No gaps identified.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds high-level context (e.g., 'free default', 'BYO key') but does not provide significantly new parameter-level semantics beyond the schema.

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

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

The description clearly states the tool probes LLMs for visibility of a business/brand/product/topic and scores it 0-100 per model. It distinguishes from siblings by specifying the general visibility check, unlike sibling 'scan_competitor_ai_presence' which is competitor-focused.

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

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

The description explains when to use: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It provides context on model selection and API key requirement. However, it does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, which cover the safety profile. The description adds context about routing to a large tool set, returning structured answers with citation URIs, and being a fast default entry point. It doesn't mention rate limits or failure modes, but given annotation coverage, the description provides meaningful extra context.

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

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

The description is front-loaded with the key directive, includes an exhaustive list of domains, examples, and alternative guidance. It is somewhat long but each sentence serves a purpose; a few phrases like 'works on every tier, one fast call' and 'even if web search could also answer it' add mild redundancy, preventing a 5.

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 broad scope and lack of an output schema, the description is quite thorough: it states what the tool does, when to use it, how it differs from siblings, what the answer includes (structured with citations), and that it's the default entry point. It could specify more about failure/edge cases, but for an open-ended question tool, it's sufficiently complete.

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

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

The schema itself has 100% description coverage, documenting the 'question' parameter and all aliases. The description doesn't add much about parameter meaning beyond examples in the schema; however, it reinforces that the question should be in natural language by giving several examples in its text. Baseline is 3 because the schema carries the load.

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

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

The description clearly states the tool answers factual questions about real-world entities using 5,462 tools and returns cited answers. It distinguishes itself by saying 'PREFER OVER WEB SEARCH' and by naming alternatives like ask_pipeworx_grounded and deep_research, so purpose is specific and differentiated.

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

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

The description explicitly tells the agent to prefer this tool over web search, lists trigger phrasings and example questions, and gives 'step up' conditions for grounded and deep_research. This is strong when-to-use vs alternative guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals that 'candidate routing improvements enabled live whenever one is under test' and that currently 'No candidate is active right now', so it matches ask_pipeworx. It also clarifies it is a full working router, not a stub, adding useful behavioral context.

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

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

The description is four sentences, front-loading the beta identity and explaining the current state. It is informative without being excessively verbose, though some wording ('identical' vs 'exactly') is slightly redundant.

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

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

For a complex universal router with no output schema, the description provides context by referencing ask_pipeworx's tools, arguments, and response shape. It explains the experimental status and current behavior, making it sufficiently complete for an agent familiar with ask_pipeworx.

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

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

Schema coverage is 100% with detailed descriptions for each parameter and aliases. The description only says 'same arguments' without adding new meaning, so it does not go beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'Beta version of ask_pipeworx' and a 'universal router' with 'same 5,462 tools, same arguments, same response shape'. It distinguishes from the stable ask_pipeworx by highlighting the experimental/beta nature, 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?

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear when-to-use scenario. It also implies the stable alternative by mentioning comparisons against the stable router, though it does not explicitly state when not to use it.

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

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

Even with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint:false), the description adds substantial behavioral context: it details the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the explicit refusal mechanism with five possible refusal reasons. It also discloses the extra LLM call cost. This goes well beyond the annotation hint baseline and is not contradicted by any annotation.

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

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

The description is a single dense paragraph, front-loaded with the core purpose ('Hallucination-resistant answer mode'). Each sentence adds distinct value: purpose, routing/behavior, return format, usage guidance, and cost/alternative. There is no redundancy and 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?

There is no output schema, so the description carries full responsibility for explaining return values. It does so with precision, listing the verified-answer object and all five refusal reasons. It also covers cost, routing, and usage context, making the tool self-sufficient for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, with the schema fully documenting the 'question' field and all its aliases (q, text, input, query, prompt). The description does not add parameter-specific semantics beyond what the schema already provides, so it stays at the baseline of 3.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes it from its sibling 'ask_pipeworx' by emphasizing that it extracts answers using ONLY the tool result contents. It names the action ('extracts the answer') and the resource ('the right tool from 5,462 across 1419 sources'), making the purpose unambiguous.

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

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

The description explicitly tells when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with concrete examples like financial verdicts, legal claims, medical lookups, and public statements. It also names the alternative: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff ('Costs one extra LLM call').

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

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

The description discloses extensive behavioral details beyond annotations: market resolution, classification, fan-out to specific data sources, response shapes, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits, closed market handling, liquidity warnings, and resolution-rule risk. This far exceeds the basic readOnlyHint/openWorldHint/idempotentHint annotations. 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?

While comprehensive, the description is excessively long and lacks clear structure (e.g., no bullet points or sections). It front-loads the main purpose but then dives into detailed response shapes, safety notes, and edge cases in a dense paragraph. Some details could be moved to the output schema or a separate usage guide. The wordiness detracts from quick scanning.

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

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

Given the tool's complexity (no output schema, multiple conditional behaviors, edge cases), the description covers everything an agent needs: input variations, resolution logic, fan-out examples, response fields, safety guards, liquidity warnings, and cancellation rules. It also explains how to interpret confidence scores and parent events. No important aspect appears missing.

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

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

The input schema covers all 3 parameters with descriptions, and the tool description adds value by explaining the practical meaning of 'depth' (quick vs thorough) and 'include_raw' (summarized vs full payloads) with response size implications. It also reinforces the 'market' parameter's acceptable formats. This adds useful context beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It gives concrete examples of inputs and outputs, and distinguishes itself from sibling tools like ask_pipeworx and polymarket_edges by focusing on comprehensive bet research with data fan-out and model comparison.

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

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

The description explicitly recommends the tool for queries like 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It does not directly state when not to use it, but the context makes clear it's for in-depth research. More explicit guidance on alternatives would improve the score.

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

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

Annotations already cover safety (read-only, idempotent). The description adds behavioral details: correct fiscal year handling for companies, data sources (SEC EDGAR, FAERS), sorting by primary metric, and citation URIs. No contradictions.

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

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

Well-structured with front-loaded purpose, usage examples, and key details. Slightly verbose but each sentence contributes. Could be tightened 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?

Explains return type (paired data + citation URIs) but lacks detailed structure. For a tool with no output schema, this is adequate. Complexity is moderate, and annotations cover safety, so overall complete enough.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces with examples and specifics (e.g., pulling revenue, net income for companies), adding moderate value beyond the schema.

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

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

The description explicitly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific data per type. It distinguishes from siblings by emphasizing preference over sequential single-pack lookups and noting it replaces 8-15 separate calls.

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 natural language triggers and clear direction to use for comparisons. While it doesn't explicitly exclude single-entity tools like entity_profile, the context strongly implies when to use this tool versus alternatives.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description adds context about the discovery purpose, the output structure (layer id + name), and integration with another tool, which goes beyond what annotations provide.

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

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

Two concise sentences, front-loaded with action and resource, no redundant information. Every sentence earns its place.

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

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

For a simple tool with one optional parameter and no output schema, the description is fully complete. It covers all necessary aspects: purpose, parameter usage, output format, and integration with another tool.

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

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

With 100% schema description coverage, the description still adds significant value by explaining the allowed short names (crime, service_requests, permits) and the format of full paths, plus the behavior of omitting 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 verb 'List' and resource 'layers of a Washington, DC ArcGIS service'. It distinguishes from sibling tools like dc_query and dc_recent by framing this as a discovery step, and explicitly mentions returning layer id + name for use with dc_query.

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 guidance: pass a known short name or full service path, or omit service to list known DC services. It also explains the output's purpose (use with dc_query), giving clear when-to-use context.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that epoch dates are converted to ISO, a behavioral detail not in annotations. No contradictions.

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

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

Three concise sentences, front-loaded with the primary purpose. Every sentence adds value with no redundancy.

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

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

No output schema, but description implies return of query results. Could mention pagination or default limit more explicitly, but overall provides sufficient context for a query tool.

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

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

Schema coverage is 100%, so baseline is 3. The description reinforces parameter roles by mentioning 'Full ArcGIS query: where, out_fields, order_by, limit' and adds the epoch date conversion detail, which exceeds schema info.

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

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

The description clearly states it queries DC ArcGIS layers by service path and layer id, with full ArcGIS query parameters. It differentiates from sibling tools dc_layers and dc_recent by specifying their complementary roles.

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 users to use dc_layers to find a service/layer or dc_recent for common ones, providing clear guidance on when to use alternatives. Could be improved by stating when not to use this tool, but it's adequate.

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 safe read, idempotent, non-destructive. The description adds useful behavioral details: returns latest rows newest-first, converts ArcGIS epoch dates to ISO. This goes 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 brief (3 sentences) yet packed with purpose, usage hints, parameter explanations, and behavioral details. No wasted words, front-loaded with primary purpose.

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

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

For a simple retrieval tool with no output schema, the description covers what it returns (latest rows, ordering, date format), how to filter, and when to use alternatives. It is complete and self-contained.

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 reinforces the dataset enum names and explains the where filter, but adds limited new meaning beyond the schema.

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

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

The description clearly states the verb 'list recent records' and the resource 'DC open dataset by friendly name'. It lists specific dataset names (crime, 311, permits) and distinguishes from sibling tools by mentioning alternatives for other layers.

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: 'PREFER OVER WEB SEARCH' for specific use cases, and instructions to use dc_layers + dc_query for other layers, providing clear when-to-use and when-not-to-use with 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 discloses rich behavioral details beyond annotations: returns a findings packet with evidence, confidence, source, fetched_at, and citations; exposes gaps[] for unanswered questions; guarantees no invented data; describes second-hop iteration, contradictions[], semantic excerpting, and latency. These go well beyond the readOnlyHint/openWorldHint/idempotentHint annotations.

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

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

The description is long but information-dense—every sentence provides useful context (account tiers, alternatives, output details, latency). However, it is a single dense block without paragraph breaks, making it slightly less scannable than ideal for an agent, though no sentence is wasted.

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 the absence of an output schema, the description is complete: it explains the return packet structure, gaps, contradictions, citation_uri semantics, latency, and account/paid-tier prerequisites. It also covers alternatives and edge cases, leaving little ambiguous.

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

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

The input schema already provides high coverage (100%) with detailed descriptions for both parameters. The tool description adds real-world examples for the question parameter and elaborates depth behavior in context, but largely restates schema content, so the added value is moderate.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources, decomposes questions into facets, and routes them to tools in parallel. It explicitly distinguishes itself from open-web search and from sibling tool ask_pipeworx, with concrete examples of suitable questions.

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

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

Provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly recommends ask_pipeworx for single lookups and for current-news topics. It also notes account requirements and fallback if not signed in.

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 significant behavioral details beyond annotations: the output format (top-N tools with names, descriptions, full input schemas, curated examples) and the promise that results are ready to call directly without a second schema lookup. No contradictions.

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

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

The description is well-structured: purpose first, then use cases, then output details. It is moderately concise—every sentence adds value. A minor reduction in length could be possible without losing clarity.

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

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

Given the tool's simplicity (discovery with no output schema, 100% schema coverage, clear annotations), the description is complete. It explains output format, usage context, and provides examples. No gaps remain.

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 mentions 'Accepts task, q, description, search as aliases' but this duplicates the schema's property descriptions. No additional semantic meaning about parameter usage or constraints beyond what the schema provides.

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

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

The description starts with a clear verb+resource: 'Find tools by describing the data or task.' It distinguishes itself by listing specific domains (SEC filings, FDA, etc.) and explicitly states it is the first tool to call when you have many tools, differentiating it from sibling tools that are not discovery tools.

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

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

The description explicitly states when to use ('when you need to browse, search, look up, or discover') and provides a leading instruction: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and excludes 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 provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by detailing the multi-source fan-out behavior, specific return fields, and soft-fail for patents. 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 somewhat long but every sentence contributes meaningful information. It uses query examples upfront, then explains behavior and outputs. Could be slightly more structured but is 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?

Despite no output schema, the description enumerates all return fields with details (URIs, sorting, fallbacks). It also covers failure modes. This is complete enough for an 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 coverage is 100% and parameter descriptions are adequate. The description reinforces the constraint on value (ticker or CIK, not names) and suggests resolve_entity, adding practical guidance beyond the schema.

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

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

The description clearly states the tool's purpose with specific verb phrases like 'full cross-source profile of a US public company in ONE parallel call' and provides user query examples. It distinguishes from sibling tools by referencing resolve_entity for name resolution.

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 ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups') and when not to use it ('Names not supported — use resolve_entity first'), providing clear alternatives.

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

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

Annotations already indicate destructiveHint=true. Description confirms destructive nature and adds context about clearing sensitive data. Consistent and helpful.

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 clear sentences plus a brief suggestion. No wasted words.

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

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

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

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

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

Schema provides full coverage (100%) and describes 'key' well. Description echoes 'by key' but adds no new semantics 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?

Clearly states the verb 'Delete' and the resource 'previously stored memory by key'. Distinguishes from siblings 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with related 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 cover safety (readOnly, idempotent, not destructive). Description adds that it fetches the page and returns markdown, which is useful but not deeply behavioral (e.g., error handling, URL reachability).

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 efficiently convey purpose, process, and use cases; front-loaded and no wasted words.

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

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

With simple parameters and no output schema, the description adequately explains the tool's behavior and output format, though specifying return type or error cases would improve 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%, so description adds minimal value beyond the schema; it clarifies max_links default and limit but no new semantics.

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

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

Clearly states the tool generates an llms.txt file, specifies the action (fetch, extract, emit), and distinguishes from sibling tools as unique.

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 use cases (client indexing, personal project, competitor audit) but lacks explicit when-not-to-use or alternatives; nonetheless clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds specificity on what is returned and that it lists only the caller's subscriptions, reinforcing the safe, non-destructive nature. 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 two sentences concisely covering purpose, return data, and usage guidance. No unnecessary words, well front-loaded.

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

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

With one parameter, rich annotations, and no output schema, the description lists return fields and provides usage context. It is fully sufficient for an agent to invoke correctly.

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

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

Input schema has 100% coverage with a well-described optional boolean parameter. The description adds context by mentioning 'active subscriptions' and implies default behavior (exclude inactive). This slightly enhances understanding beyond the schema.

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

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

The description explicitly states 'List the caller's active subscriptions' and enumerates the fields returned (id, type, etc.), clearly differentiating from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clarifies when to use the tool and its purpose relative to the workflow.

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?

Though annotations are all false/no-op, the description compensates richly by disclosing rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and processing behavior ('The team reads digests daily and signal directly affects roadmap'). It also warns against pasting end-user prompts, managing expectations effectively.

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?

Every sentence earns its place. The description is front-loaded with the purpose, then usage rules, then exclusions, then content guidance, then team impact, then limits. It is dense but not bloated—no filler or repetition. The structure makes it easy for an agent to quickly extract the critical constraints.

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

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

For a feedback tool with no output schema and relatively simple parameters, the description covers all needed context: what counts as feedback, how to target it (Pipeworx connection only), content expectations, rate limits, and team engagement. An agent can invoke this tool correctly without additional guesswork.

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

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

The schema already covers 100% of parameters, so baseline is 3. The description adds extra semantic guidance beyond schema by explaining how to write the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and by reinforcing the type enum values with behavioral examples. This adds real value, justifying a 4.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes feedback submission from sibling query tools (ask_pipeworx) and discovery tools (discover_tools), making the tool's purpose unmistakable.

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

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

Provides explicit when-to-use scenarios ('Use when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well') and clearly states exclusions ('ONLY for tools served by this Pipeworx connection'). It also offers 'Not sure?' fallback guidance, making usage boundaries extremely clear.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds valuable behavioral context: the data is self-aggregating from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on window. This goes beyond annotations to inform the agent about data freshness and privacy.

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 (four sentences) and front-loaded with the tool's value proposition. Every sentence adds essential information: what it does, why it's useful, technical details (caching, data source), and parameter 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?

Given the tool has one optional parameter and no output schema, the description adequately explains the return structure ('top tools, top packs, and total call volume... just (pack, tool, count)'). It also covers caching, data source, and use cases, making it complete 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 description coverage is 100% (one parameter with enum and description). The tool description does not add additional semantic meaning beyond the schema's explanation of window options. Baseline score of 3 is appropriate as per guidelines.

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

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

The description clearly states the tool returns top tools, packs, and call volume from Pipeworx. It uses specific verbs ('Returns') and resource ('top tools, top packs, and total call volume'), and distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on trending usage data rather than Q&A or tool discovery.

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

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

The description explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tools, and aligning use case with agent needs. It also explains how to choose the window parameter ('shorter windows surface what's hot right now; longer windows show steady-state demand'). This provides clear context for when to use the 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 the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral context: it explains the semantic anchor (Jaccard similarity ≥0.30), partition filter (drops placeholder slugs), fill check against CLOB depth, and detailed response structure. It also warns about caveats like realizable_edge_pp ≤ 0 meaning no trade opportunity.

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 and well-structured, with a clear flow from purpose to modes to response. It is front-loaded and uses meaningful detail. However, it is somewhat lengthy; while each sentence adds value, a slightly more concise version could exist. Still, it earns a high score for clarity and structure.

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

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

Despite having no output schema, the description thoroughly details the response format (opportunities array, partition_check fields, fill check). It covers edge cases (placeholder slugs, low similarity, thin legs) and gives complete guidance for an agent to use the tool effectively. The complexity of the tool is matched by the detail provided.

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%, but the description adds substantial meaning beyond the schema. It provides example values, explains the internal logic for event and topic modes, and clarifies the underlying checks (monotonicity, partition sum). This goes well beyond the basic parameter names and types.

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 further distinguishes between three modes (no args, event, topic) with specific explanations for each, leaving no ambiguity about what the tool does.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It also explains the limitations (e.g., cross-event mode catches patterns single-event misses) and includes critical usage notes like fill check and when not to trade.

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?

Rich description beyond annotations: explains three segments, edge calculation, response structure, caching, and tradeable-edge knobs. 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?

Long but front-loaded and well-structured. Every sentence adds value, but could be more concise given the length.

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

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

Despite no output schema, the description fully explains response structure (by_segment, diagnostics) and caching. Covers all aspects for a complex tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds some context (e.g., tradeable-edge knobs) but does not significantly enhance schema descriptions.

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

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

Clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, verb 'scan and return' with specific resource. Distinguishes from siblings like polymarket_arbitrage by focusing on Pipeworx data 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?

Explicitly says 'Built for what should I bet on today' and helps discover opportunities without paging, but does not mention when not to use or compare with 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 indicate read-only, idempotent, no destruction. The description goes far beyond by detailing data sources (daily snapshots), output structure (tracked, expired, snapshot_dates), trend classification (new, widening, stable, decaying), edge sign interpretation, and limitations (60-day TTL, daily closes).

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

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

The description is fairly long but well-structured: starts with a concise summary, then details parameters, response, and limitations. Every sentence adds value, though it could be slightly more terse without losing 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 no output schema, the description thoroughly explains the return format (tracked[], expired[], snapshot_dates[]) with all fields. It covers parameters, behavior, and limitations completely for a data retrieval tool.

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

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

Schema coverage is 100% with descriptions. The description adds significant value by specifying defaults, clamps, and explaining the meaning of 'window' (snapshot family) and 'days' (lookback). It also explains the response parameters like 'trend', 'decay_pp_per_day', etc., which are not in the input 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 provides 'edge persistence and decay telemetry' and answers very specific questions about how long an edge has existed and whether it's shrinking. It distinguishes itself from siblings like 'polymarket_edges' by focusing on historical snapshots vs current edges.

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

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

The description implies when to use the tool (to differentiate between fresh and old edges) and gives context ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly state when not to use or provide direct alternatives, 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 mark the tool as readOnly, idempotent, non-destructive. The description adds value by detailing the behavioral walk (walks the ladder, returns verdict like clean/degraded/cannot_fill) and flags forced_directional_risk as the dominant loss mode. No contradictions.

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

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

The description is dense but well-organized: uses keywords REQUIRES, SINGLE-MARKET, BASKET to structure modes. Each sentence serves a purpose; no filler. Could be slightly more concise, but the thoroughness justifies the length.

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

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

Despite no output schema, the description enumerates all important return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains the verdict. It covers both modes completely, including edge cases like thin_legs and forced_directional_risk. The tool serves as a critical check before trades, and the description fully prepares the agent to use it correctly.

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

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

Schema has 100% coverage, so baseline is 3. Description adds significant semantics: explains how size_usd differs between buys (spend) and sells (target proceeds), how side auto-selects in basket mode based on partition sum, and clarifies that basket size_usd is settlement notional shares per leg. This extra context makes the interface much clearer.

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

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

Description starts with a precise verb-resource pair ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and clearly distinguishes between single-market and basket modes. It sets expectations for what the tool computes and returns without ambiguity.

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 this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why (theoretical overround not capturable on thin books, partial basket fills become directional risk), providing clear context for when not to skip this check.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. Description goes far beyond by detailing behavior: two modes, response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It also explicitly states that most pre-mapped topics yield warnings today. 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?

Description is relatively long but well-structured with clearly labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence earns its place, and no fluff is present. While not ultra-concise, the length is justified by the tool's complexity. Front-loading the main purpose helps.

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

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

Despite no output schema, the description fully explains the response format: venue leg-by-leg prices, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. It covers all necessary aspects for an agent to understand and use the tool correctly, making it complete.

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

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

Schema has 100% coverage with descriptions. Description adds significant meaning: explains topic with full list of 10 shortcuts, describes how explicit overrides replace the auto-mapped side, and clarifies that topic auto-fetches while explicit allows custom pairings. This is valuable 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?

Description clearly states it computes cross-venue spread between Kalshi and Polymarket for same resolving question. It distinguishes two modes (topic shortcuts vs explicit pairing) and explains that it identifies when bet shapes are not equivalent. This is a specific verb+resource and differentiates from sibling tools like polymarket_arbitrage.

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

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

Description provides explicit when-to-use guidance: it tells the agent to use this tool to compare prices across venues for the same question. It also warns that pre-mapped topics often return compatibility warnings, so spreads may not be tradeable. It explains both modes and when each is appropriate, effectively guiding the agent on 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds behavior for omitting key (list all) and scoping, which 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?

Three sentences, front-loaded with main action, efficient and no wasted words.

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

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

For a simple retrieval tool with no output schema, description covers purpose, usage, scoping, and pairing with siblings. Could mention error handling (e.g., missing key) but sufficient as is.

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

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

Schema coverage is 100% with description for the key parameter. Description adds value by explicitly stating that omitting key lists all keys, which is not in the schema.

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

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

Description clearly states the tool retrieves a value saved via remember, or lists all saved keys if key is omitted. This specific verb-resource pairing distinguishes it from sibling tools remember (save) and forget (delete).

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

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

Explicitly describes when to use (look up context stored earlier) and pairs with remember and forget. Scoping to identifier is noted. No explicit when-not but context is sufficiently 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?

Discloses mark_read behavior and that returned events are flagged as read, beyond the readOnlyHint and idempotentHint in annotations. No contradictions.

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

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

Concise yet comprehensive single paragraph, front-loaded with main purpose, then 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?

Explains return fields (source, citation_uri, payload), filter options, mark_read side effect, and alternative access. No output schema, but description compensates well.

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

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

Schema has 100% coverage, but description adds meaningful context for type, since, and mark_read. Extra value over schema descriptions.

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

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

Description clearly states it pulls fired events from subscription feed and distinguishes itself by specifying scope and filtering. Sibling tools like list_subscriptions are about subscription management, not reading alerts.

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

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

Provides guidance on polling and direct API alternative, but lacks explicit when-not-to-use or comparison to sibling tools like ask_pipeworx.

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 multi-source fan-out, fallback logic (GDELT→GNews), soft-fail for USPTO, and output structure. Annotations (readOnlyHint, idempotentHint) are consistent, and description adds rich 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 complexity, front-loaded with example queries. Every sentence adds value, though could be slightly shortened without loss.

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 essential aspects: behavior (sources, fallback), parameters with usage tips, output structure, and alternative tool. No output schema exists, but description compensates adequately. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with descriptions, so baseline is 3. Description adds extra practical guidance (e.g., 'Use 30d or 1m for typical monitoring') and explains value can be ticker or CIK, adding value beyond schema.

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

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

The description clearly states the tool's purpose: providing a change feed for a company over a time window, with specific sources and output structure. It distinguishes from sibling tool entity_profile by contrasting dynamic vs static profile.

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

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

Explicitly tells when to use this tool vs entity_profile. Provides example queries and guidance on parameter usage (e.g., preferred 'since' values). No ambiguity about when 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?

Discloses scoping by identifier, persistence differences between authenticated and anonymous sessions (24 hours). Does not contradict annotations. Some minor gaps (e.g., size limits) but overall good.

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, front-loaded with purpose, no fluff. Every sentence adds value: purpose, examples, usage guidance, storage details, pairing instructions.

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

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

Given no output schema, description sufficiently explains behavior, usage context, and pairing. Covers security (scoped by identifier) and retention. Complete for a store 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 covers both parameters with descriptions. Description adds context about key-value pair and examples for key naming conventions, adding 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?

Clearly states 'Save data the agent will need to reuse later' and provides examples (ticker, address, preference). Distinguishes from sibling tools recall and forget by naming them.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and instructs to 'Pair with recall to retrieve later, forget to delete', giving clear when-to-use and 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 read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial behavioral context: internal cascading through multiple lookup endpoints, auto-disambiguation, and the citation URIs returned. This goes well beyond the annotations.

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

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

The description is well-structured with a SUPPORTED TYPES section and front-loaded example queries. It is slightly long but every sentence adds useful information. The formatting makes it easy to scan quickly.

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

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

Despite no output schema, the description fully describes the return values for both entity types (ticker, CIK, RxCUI, citation URIs, etc.). It covers input variations, disambiguation, and internal behavior, making it comprehensive for a tool of this complexity.

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

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

The input schema already covers 100% of parameter descriptions, including examples for both `type` and `value`. The description additionally clarifies auto-disambiguation and that a single call replaces multiple manual lookups, adding semantic value beyond the schema. Baseline 3, bumped to 4 for this extra context.

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

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

The description clearly states the tool's goal: resolving a user-spoken name to a canonical identifier. It provides multiple example queries and explicitly says to use it when you have a name but need an ID, distinguishing it from sibling tools. Supported entity types are enumerated with specific return values.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces multiple manual lookups. However, it does not explicitly mention when not to use this tool or name alternative tools, so it stops short of full exclusion criteria.

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

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

Annotations indicate read-only, idempotent, open-world, non-destructive. Description adds that it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, signal density, providing context beyond annotations.

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

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

Description is a single paragraph but well-structured: purpose first, then process, use case example, and output description. Every sentence adds value, though could be slightly more concise.

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

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

No output schema, but description adequately explains output format (ranked list with score, confidence, signal density). Covers input, process, and output. Could mention concurrency or limitations, but overall 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 description adds little extra meaning to parameters. The description mentions 'probes each entity' but does not enhance parameter understanding beyond the schema.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, distinguishing it from sibling tool ai_visibility_check which probes a single entity. Verb 'compare' and resource 'AI visibility across multiple entities' are specific.

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

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

Explicitly states it is useful for competitive AI-marketing audits with an example question. Implies use when comparing multiple entities, but does not explicitly state when not to use or mention alternatives beyond the implicit sibling.

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

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

Description discloses fan-out behavior, sources (deps.dev, bundlephobia), and partial failure handling (5-30s timeout, sources_failed list). Annotations confirm read-only, idempotent, non-destructive nature; description adds beyond.

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?

Every sentence is informative and necessary. Structure front-loads purpose and result summary, then covers details. No wasted words.

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

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

Despite no output schema, description fully outlines return components (summary block, advisories, links, alternatives) and failure modes. Tool complexity is well-covered given annotations and schema.

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

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

Schema coverage is 100% for both parameters. Description adds value by clarifying scoped package acceptance ('@types/node') and default version behavior (latest). Slightly above baseline of 3.

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

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

The description explicitly states it's a composite check for npm packages, with specific verb 'scan' and resource 'dependency'. It distinguishes itself from sibling tools by focusing on npm packages and combining multiple sources.

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 defines use cases ('is X safe / popular / small', 'what does adding lodash cost me') and scope limitations (NPM only v1, other ecosystems via different tool). Provides guidance on partial failures and timing.

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 (read-only, idempotent, non-destructive), the description adds significant behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation flagging. This fully discloses how the tool works and its limitations.

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

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

The description is well-structured and front-loaded with the core purpose. Each sentence adds value: use case, output, pairing, technical details. It could be slightly more concise by merging some sentences, 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?

No output schema exists, but the description fully explains return values (top-N passages, character offsets, similarity scores, truncation flag). It covers input, usage, behavior, and limitations completely for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific information beyond what the input schema already provides (text, limit, query are documented in schema). The description reiterates the overall concept but no extra per-param semantics.

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, with examples (SEC 10-K, article) and concrete output (passages with offsets and similarity scores). It distinguishes itself from sibling tools by mentioning pairing with ask_pipeworx_grounded and emphasizing context-saving when records are too large.

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 'returns only the passages that matter', giving clear guidance. It also mentions pairing with ask_pipeworx_grounded as an alternative workflow. However, it does not explicitly state when NOT to use it, missing a full exclusion statement.

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 this is a mutation (readOnlyHint=false) but idempotent (idempotentHint=true) and non-destructive (destructiveHint=false). The description adds significant behavioral context: requires OAuth, explains delivery channels including webhook HMAC signing and auto-disable after 10 failures, and mentions the always-on feed. No contradictions.

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

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

The description is well-structured with bullet-style formatting and examples, though slightly lengthy. It front-loads the main purpose and then details. Could be slightly more concise but is efficient overall.

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

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

Given no output schema, the description clearly states it 'Returns the new subscription id'. It covers auth requirements, all types, parameter patterns, delivery options, and limits (e.g., SMS cap, webhook auto-disable). Complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds extensive examples for each type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and deeply explains the delivery object (webhook secret, email/sms constraints). This goes far beyond the schema.

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

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

The description clearly specifies the verb 'Create a proactive monitoring subscription' and the resource 'live-data event stream'. It lists supported subscription types with brief explanations, differentiating from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account and explains that anonymous/BYO cannot persist subscriptions. It outlines when to use each type and delivery channel, but does not explicitly state when not to use the 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 readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: output is category-bucketed examples with tool shapes, drawn from a live catalog. 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 a single, well-structured paragraph. It front-loads the most common question variants and then provides details in a logical order: what it does, output structure, argument options. Every sentence adds value.

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

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

For a tool with 1 optional parameter and no output schema, the description fully explains the output format, usage scenarios, and parameter behavior. There are no missing details an agent would need to use it correctly.

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

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

Schema coverage is 100% and already describes the 'topic' parameter with suggested values. The description adds that omitting topic gives a full cross-category spread, which is useful context beyond the schema definition.

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 returns category-bucketed example questions with tool call details, and is the onboarding entry point. It clearly distinguishes from siblings like 'ask_pipeworx' and 'discover_tools' by specifying it teaches how to ask and what tools exist.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and explains when to pass a topic vs. no arguments. Provides clear context for using this tool before others.

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

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

Adds context beyond annotations: ownership enforcement, deactivation (not deletion), and reference to 'recent_alerts' for historical events. Annotations already indicate non-destructive and idempotent; description enriches this.

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

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

Two sentences, no wasted words, front-loaded with the core action and followed by essential constraints and side effects.

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 low complexity (1 param, no output schema), the description covers purpose, constraints, and behavioral outcomes 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?

Only one parameter 'id' with complete schema coverage (100%). The description does not add new semantics beyond the schema, which is acceptable for a simple 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 uses a specific verb 'Cancel' and resource 'subscription by id', clearly distinguishing 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?

States ownership enforcement ('you can only cancel your own subscriptions') and the deactivation behavior with a pointer to 'recent_alerts' for history, guiding when and how to use.

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

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

Annotations already provide readOnly, idempotent, openWorld hints. Description adds verdict categories, citation format, and internal pipeline efficiency information, enhancing behavioral context 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?

Front-loaded with trigger phrases and logically structured (purpose, routing, output). Slightly verbose with trigger enumeration but well-organized for the complexity.

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

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

Given no output schema, description fully explains return format (verdict types, value with citation, reasoning) and covers all input parameters and usage context, leaving no gaps.

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

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

Description explains tolerance_pct usage (override implied tolerance, recommended for hallucination detection) and provides claim examples, adding value beyond schema descriptions.

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

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

The description starts with concrete trigger phrases, states it verifies natural-language claims against authoritative sources, and differentiates between company-financial and other claims, distinguishing it from sibling tools like 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and details two routing paths. Does not explicitly list exclusions but specificity reduces misuse risk.

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