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 provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable behavior beyond these: it routes to one of 5,798 tools, fills arguments automatically, and returns answers with stable pipeworx:// citation URIs. It also notes news routing behavior. No contradiction with annotations.

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

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

The description is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and every section adds value: scope, behavior, triggers, examples, and exclusions. However, it is long and somewhat dense, and the exhaustive source list and repeated trigger phrases could be trimmed without losing meaning.

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

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

For a read-only meta-router with no output schema, the description tells the agent what the tool does, when to prefer it, when to choose a sibling, what kinds of questions work, and what the response contains (structured answers with citation URIs). This is sufficient for correct invocation.

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

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

Schema description coverage is 100% and all parameters are aliases for 'question'. The description provides useful examples and trigger phrasing, but it does not add substantial parameter-level semantics beyond what the schema already states. Baseline of 3 is appropriate.

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

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

The description names a specific action ('Routes the question to ... tools', 'returns the structured answer'), a clear resource domain (authoritative structured data from SEC, FDA, FRED, etc.), and explicitly contrasts itself with web search and sibling tools. It makes the tool's scope and intent immediately identifiable.

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

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

The description gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest'), concrete examples, and direct routing guidance: use ask_pipeworx_grounded for grounded single-answer questions, deep_research for broad/multi-part questions, and this tool as the default. This clearly distinguishes when to use it 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behavioral traits: routing improvements can be enabled live during tests, the current active-candidate status, and that outputs are compared against the stable router to inform merges. It also states that with no candidate active it behaves identically to ask_pipeworx, which is valuable transparency for an experimental tool.

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 information-dense and front-loads the most important fact — that this is a beta version identical to ask_pipeworx — before explaining current status and usage. The specific tool count and retirement date add context but are slightly more detail than strictly necessary, so it is efficient though not maximally lean.

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 experimental routing tool with no output schema, the description covers purpose, current behavior, usage, and experimental nature well. It references 'same response shape' as ask_pipeworx rather than describing the response directly, which is a small gap if the agent does not already know ask_pipeworx's shape, but the pointer is clear and sufficient in context.

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

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

Input schema coverage is 100%, with all six parameters described as aliases for 'question'. The description confirms 'same arguments' as ask_pipeworx but adds no new semantic detail beyond the schema. This is the baseline score appropriate when the schema already carries the parameter meaning.

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

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

The description clearly identifies a specific action and resource: it is the beta version of ask_pipeworx, a universal router over 5,798 tools with the same arguments and response shape. It explicitly differentiates itself from the stable ask_pipeworx by noting candidate routing improvements, and the phrase 'identical universal router' pins down the core purpose 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?

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. It also clarifies the current state (no candidate active, so it matches ask_pipeworx exactly) and addresses a likely misconception by stating 'Falls back to nothing — this IS a full working router.' It does not explicitly enumerate when not to use it versus the grounded sibling, but the stable-versus-experimental distinction is clear enough.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond them by disclosing the refusal behavior, the exact success and error return shapes, and the grounding constraint that the answer is extracted only from the tool result. 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 dense but every sentence earns its place: purpose, routing, extraction behavior, return shape, refusal reasons, use cases, and cost comparison. Key differentiating information is front-loaded, and the structure flows logically from what the tool does to when to use it.

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

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

Despite having no output schema, the description fully specifies the success response fields and refusal reason values. It also covers cost trade-offs, sibling distinction, supported question types, and the anti-hallucination guarantee, so an agent has all necessary context to invoke it correctly.

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

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

Schema description coverage is 100%, so the parameter is already fully documented in the schema, including aliases like query, q, prompt, text, and input. The tool description itself adds no new parameter-level meaning beyond what the schema already provides, making baseline 3 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 uses a specific verb (ask/extract) and clearly identifies the resource: a grounded, hallucination-resistant answer mode that routes across 5,798 tools and 1,517 sources. It immediately distinguishes itself from ask_pipeworx by emphasizing extraction strictly from tool results, so an agent can differentiate it from siblings without opening schemas.

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

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

Explicitly states when to use: whenever an answer will be quoted, cited, or acted on, and when facts must not be invented. It also gives the exclusion: prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This is strong when-to-use versus 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?

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?

Annotations already signal readOnly/idempotent/non-destructive, and the description adds rich behavior beyond that: auth and paid-tier requirements, parallel decomposition, gap[] reporting, contradiction[] scanning, citation_uri only when fetchable, semantic excerpting, and latency expectations. It also discloses that the tool is grounded in structured sources, not open-web search.

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 the length is mostly earned for a complex multi-step tool: auth, use cases, output shape, depth behavior, citation caveats, and latency. It is front-loaded with the prerequisite before the main explanation, though a couple of depth-related details are repeated across the description and schema.

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

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

With no output schema, the description carries the burden of explaining return values, and it does: findings packet, confidence/source/fetched_at, citations, gaps[], contradictions[], and excerpt behavior. Combined with the annotations and rich input schema, an agent has everything needed to decide whether to call the tool and how to set expectations.

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

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

Schema covers all 2 parameters (100%) with detailed depth semantics, so the baseline is 3. The description adds non-obvious details: 'thorough' requires a paid plan, the behavior of gap recovery and contradiction scans per depth, and the approximate latency profile. There is minor overlap with the schema but the added context justifies 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 names a specific operation ('Decomposes your question into focused facets, routes each to the right ... tools ... and returns a findings packet') over a specific resource (Pipeworx's 1517 structured data sources), and distinguishes itself from open-web search. It also explicitly contrasts with ask_pipeworx, so an agent can tell them apart.

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

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

Gives explicit when-to-use advice: broad/multi-part questions over structured data, and an explicit alternative for single lookups ('use ask_pipeworx instead'). Also states the account prerequisite and routes unsigned-in users to ask_pipeworx, plus the paid threshold for the 'thorough' depth.

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?

The annotations already establish read-only, idempotent, open-world behavior, and the description goes far beyond them: it discloses the parallel fan-out across sources, the GDELT→GNews fallback, the soft-fail of USPTO patents after the API sunset, and the semantics of empty sections ('an empty section is a real "no data", not a bug'). It also explains resolved:false behavior for private companies. This is rich, non-obvious behavioral context that annotations alone would not convey.

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

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

The description is long, but it is information-dense and every clause earns its place for a tool with this many sources and edge cases. The core purpose and usage preference are front-loaded; the rest is a structured enumeration of return fields and failure semantics. It could be slightly more scannable with bullets, but it is not padded.

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

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

With no output schema, the description fully compensates by enumerating every return section (cik, company_name, resolved_from/to, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, sources_used, sources_failed) and explaining edge semantics like empty FDA sections, patent soft-fail, and private-company responses. Nothing an agent needs to invoke or interpret this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial value beyond the schema: it states that names resolve via SEC EDGAR company-name match, that type accepts 'company' or 'ticker' interchangeably with identical behavior, and enumerates all accepted value shapes (ticker, zero-padded CIK, name). The 'person/place coming soon' note also clarifies the current semantic boundary.

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

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

The description opens with concrete example queries and a crisp definition: 'full cross-source profile of a US public company in ONE parallel call.' It clearly names the verb, resource, and scope, and distinguishes itself from the sibling tools that do narrower or comparative work (e.g., resolve_entity, compare_entities) by emphasizing the holistic, multi-source nature.

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

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

Explicit guidance is present: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This tells the agent when to select it over an alternative approach. It could be stronger by naming specific sibling tools like resolve_entity or compare_entities as exclusions/alternatives, so it misses the highest bar, but the context is clear.

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

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

Annotations already 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?

Since all annotations are false and carry no safety signals, the description carries the full burden. It discloses rate limiting (5 per identifier per day), quota impact (free, doesn't count), return value (claim_token), follow-up mechanism, and human processes (team reads daily, signal affects roadmap). This is rich, honest behavioral context beyond structured fields.

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 every sentence earns its place: purpose, use cases, scope restriction, message guidance, token flow, rate limit, and quota. Information is front-loaded and there is no redundancy. The structure flows logically from what → when → how → consequences.

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

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

Given no output schema, the description explains the primary return (claim_token) and subsequent read of the token. It covers scope limitations, rate limits, and message format expectations. All four parameters are covered by schema descriptions, and the description adds the behavioral context needed to invoke correctly. Complete for a feedback tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the claim_token round-trip flow and emphasizing context should reference Pipeworx tools/packs, which reinforces the context parameter semantics. It also clarifies that context is optional and only relevant for tool/pack/vertical. This elevates it above baseline.

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

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

Description clearly states the tool's purpose with a specific verb ('Tell the Pipeworx team') and enumerates the feedback categories (broken, missing, praise). It distinguishes itself from sibling tools by explicitly scoping to Pipeworx connection tools and framing feedback as bug/feature/data_gap/praise, unlike ask_pipeworx which answers 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: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: if the tool came from a different MCP server, file it with that server instead. This fully covers usage scenarios 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 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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral disclosure: matching is keyword/word-overlap based, not a shared resolution source, Kalshi fees are not modeled so spreads are gross not net, unclassified legs are never paired, and warning fields can be non-empty even when matched_pairs>0. This goes well beyond what annotations convey.

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

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

The description is very long, but it is structured with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, fees note) and every sentence carries substantive caveats or behavior. It is not concise in word count, but the density of important information justifies the length for a complex tool with no output schema.

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

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

Given the tool's complexity and absence of an output schema, the description is unusually complete: it names response fields like spread[].top_spreads_pp, temporal_alignment, skipped_unclassified, low_confidence_pairs[], compatibility_codes[], and spread.fees_note. It also explains edge cases such as 'null means it could not be computed, not that the two sides align.' An agent has enough context to invoke this tool and interpret its result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: topic is defined as a pre-mapped macro shortcut, explicit parameters are defined as overriding the topic-mapped side, and it clarifies that both modes run the same token-overlap matcher. It doesn't add format syntax beyond the schema, but it explains how the parameters interact.

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 crisp statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names both venues, the resource (spread), and the core condition (same resolving question), making it clearly distinguishable from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description explicitly presents TWO MODES — topic shortcuts versus explicit event ticker/slug pairings — and explains that both run the identical matcher. It also includes practical guidance such as 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly compare against sibling tools, but within this tool's scope the usage context is 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 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 readOnly/openWorld/idempotent, and the description adds substantial behavioral context: identifiers are labelled by source, unresolved identifiers are explicitly returned under `unresolved`, ambiguous matches return `figi_candidates`, LEI/FIGI enrichment degrades gracefully, and internal cascading replaces multiple manual lookups. This goes well beyond what annotations provide.

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

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

The description is information-dense but poorly structured: long parenthetical asides, nested clauses, and a wall-of-text format make it harder to scan. Every sentence carries useful content, but the presentation sacrifices clarity; a bulleted breakdown by type would earn a higher score.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: per-type outputs, ambiguity handling via `figi_candidates`, explicit `unresolved` results, source labelling, graceful degradation, and supported input forms. It is complete enough for an agent to invoke the tool and interpret results correctly.

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

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

Input schema coverage is 100% and the schema's value description is already detailed. The description further adds value by documenting that company inputs also accept ISIN, explaining ISIN-to-LEI resolution, and clarifying that the FIGI lookup matches instrument names so trailing security-class words fail. This is meaningfully more than the schema alone 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 states a specific verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clarifies its role as the first-step resolver and lists concrete entity types (company, drug), making its purpose unmistakable and distinguishing it from downstream tools that consume the IDs it produces.

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 invocation guidance: 'Use FIRST whenever you have a name but need an ID' and illustrates with natural-language query patterns. However, it does not explicitly name sibling alternatives such as entity_profile or compare_entities, nor state when NOT to use this tool, so the usage guidance is clear but lacks formal exclusions.

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

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

Annotations indicate read-only, idempotent, 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?

The description adds substantial context beyond the readOnly/openWorld/idempotent annotations: it details the different verdicts, the meaning of could_not_verify versus unsupported, and the presence of verification_error{stage,detail}. It warns that could_not_verify is not evidence for or against the claim—this is exactly the kind of behavioral nuance an agent needs. No contradictions with annotations.

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

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

The description is longer than average but every sentence carries weight: examples, routing, return value, and critical error semantics are all present. The structure is front-loaded with the purpose and then builds outward logically. It could be slightly more compact, but the density is justified by the tool's complexity.

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

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

Given the tool's moderate complexity, a 2-param schema with high coverage, and no output schema, the description covers the key mental model: claim types, routing, verdicts, citations, and error semantics. It does not explicitly document all possible edge cases (e.g., what happens with ambiguous claims) but is complete enough for correct invocation and interpretation of results.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already explains claim with examples and tolerance_pct with its override semantics. The description reinforces that exact percent-delta math is used and mentions the tolerance context, but it does not add much meaning beyond the schema's parameter descriptions. It neither improves nor hurts the agent's understanding of the parameters.

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

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

The description starts with a clear, specific verb-resource pair: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by naming exact intents ('fact check', 'verify the claim') and by the unique verdict vocabulary (confirmed, refuted, etc.). The description makes it immediately clear what this tool does that ask_pipeworx_grounded or other search tools do not.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the internal routing (financial via EDGAR/XBRL, other via grounded pipeline) and positions it as a replacement for 4–6 sequential calls. However, it does not explicitly name sibling alternatives or state when not to use it (e.g., for non-factual questions), so it falls short of a full 5.

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