Data Detroit

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about probing multiple models, per-model return structure (score, confidence, signals, raw_response), combined view, and key handling for Anthropic. It does not contradict annotations. Missing potential rate limits or cost details, but overall complements annotations well.

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: first describes core action and output, second covers key parameters and cost implications, third lists use cases. No wasted words, information is front-loaded, and every sentence adds value. Ideal length for quick comprehension.

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, so the description must cover return structure. It does so clearly: per-model fields and combined view. It also explains all four parameters, default behavior, and key usage. For a tool with moderate complexity and rich annotations, this is fully adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining default model behavior, that 'models' array is optional and defaults to workers-ai, that '_apiKey' is passed through to Anthropic, and that 'context' helps disambiguate entities. This goes beyond the schema's minimal descriptions.

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

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

The description explicitly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It clearly distinguishes from sibling tools by focusing on AI visibility audits, brand checks, and competitive monitoring. Specific verb 'Probe' and resource 'LLMs' with quantified output make purpose unmistakable.

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

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

The description gives concrete use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default model and optional Anthropic usage with BYO key. However, it does not explicitly state when not to use this tool or contrast with siblings like scan_competitor_ai_presence, leaving some ambiguity for agent decision-making.

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

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

Annotations already establish readOnly, idempotent, open-world, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it reveals that the tool routes to thousands of tools, fills arguments autonomously, and returns stable citation URIs. No contradictions with annotations were 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?

The description front-loads its most important guidance, but it becomes highly repetitive: the 'START HERE for most questions — even if web search could also answer it. Examples: ...' block repeats several times. This wastes tokens and violates the expectation that 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 free-text factual query tool with no output schema, the description is quite complete: it explains scope, provides trigger phrases, gives multiple examples, and describes the output format (structured answer with citation URIs). It could mention limitations or sibling-tool boundaries, but it is not missing core information needed to invoke the 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?

Parameter schema coverage is 100%: all parameters are aliases for the same natural-language question, and the schema documents each alias. The description adds little parameter-level meaning, but the schema already carries the burden, so the baseline of 3 is appropriate.

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

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

The description clearly identifies a specific verb+resource: it routes a user's factual question to one of 5,798 tools across 1,517 verified sources and returns a structured answer with pipeworx:// citation URIs. It distinguishes itself from web search, but it does not differentiate from sibling tools like ask_pipeworx_beta or ask_pipeworx_grounded, so it does not earn a 5.

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, high-signal guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It lists concrete example queries and explicitly says this should be used even when web search could also answer, making the routing decision very 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that candidate routing improvements may be live during testing, that no candidate is currently active, and that it 'falls back to nothing' as a full working router. This is substantial behavioral context an agent needs before invoking an experimental variant.

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 tool's identity and uses every sentence to add necessary context: experimental status, current parity with stable, usage direction, and what falls back. Despite length, there is no fluff.

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

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

For a beta twin of an existing tool, the description covers the essential runtime facts: identical tool set, identical arguments, identical response shape, current no-op candidate state, and how routing decisions are made. Nothing an agent needs to call it 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 description coverage is 100%, so the schema already fully documents the single logical parameter and its aliases. The description adds no new parameter-level detail because it references 'same arguments' as ask_pipeworx, which is consistent but not additional semantic value.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx and a 'universal router' with the same tools, arguments, and response shape. It also distinguishes it from the stable version by explaining that it carries candidate routing improvements, giving an agent a concrete identity and scope.

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

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

It explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router to decide merges. This gives clear when-to-use guidance and names the relevant alternative.

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

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

The description goes well beyond the annotations by specifying exact success and refusal response shapes, listing refusal reasons, emphasizing evidence extraction from the tool result only, and disclosing the extra LLM call cost. It matches and complements the readOnly/idempotent annotations without contradiction.

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

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

The description is dense but every sentence earns its place: purpose, routing, return behavior, refusal reasons, when to use, and cost comparison. It is front-loaded with the core distinguishing attribute and avoids repetition of schema or annotation content.

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

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

Given there is no output schema, the description fully compensates by documenting both success and refusal return shapes. It also covers when to prefer the non-grounded sibling, cost implications, and the internal routing scope, making the tool self-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?

Schema description coverage is 100%, so the parameter semantics are already fully documented in the input schema: one natural language question with multiple aliases. The description adds no further detail about how to phrase the question or how the parameter is used, so the baseline of 3 is appropriate.

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

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

The description clearly identifies a grounded, hallucination-resistant answer mode and contrasts it with ask_pipeworx via 'Same routing as ask_pipeworx' while emphasizing the difference: it extracts answers only from tool results. It names the return contract and refusal behavior, so an agent knows exactly what this tool does and how it differs from siblings.

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 this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. It also names the alternative, ask_pipeworx, and directs casual lookups there because of the extra LLM call cost. This leaves no ambiguity about selection.

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

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

Annotations already indicate readOnly, idempotent, open-world. Description adds extensive behavioral details: market resolution, classification, fan-out, response shapes, status codes (low_confidence_match, market_closed_or_inactive), tradeability warnings, cancellation rule parsing, and NEWS fallback handling. 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?

Description is long but dense with unique information. Each section (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) adds value. Front-loaded summary. Could be slightly more streamlined, but no wasted sentences.

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

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

Given 3 parameters, no output schema, and multiple response shapes, description covers market matching, fan-out examples, evidence structure, safety mechanisms, and resolution risks. Extremely comprehensive for an agent to use correctly.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining 'depth' enum values (quick vs thorough), 'include_raw' effect, and gives examples for 'market' parameter. This goes beyond schema definitions.

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?

Describes specific action: research a Polymarket bet by pulling Pipeworx data. Includes verb 'research', resource 'Polymarket bet', and method 'pulling Pipeworx data'. Distinguishes from sibling tools like polymarket_edges by focusing on evidence packet and market-vs-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?

States explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While it does not specify when not to use or list alternatives, the use cases are clear and context-rich.

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, and idempotent hints. The description adds rich behavioral context: it pulls specific financial data from SEC EDGAR/XBRL with proper fiscal-year handling, FAERS data for drugs, sorts results by primary metric, and returns paired data with citation URIs. This far exceeds the annotation information.

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

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

The description is a single paragraph but front-loads key queries and is dense with useful information. Every sentence contributes value, though a slight structural break (e.g., separating company vs. drug details) could improve readability. No wasted words.

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

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

Given the tool's complexity (two entity types with distinct data sources), the description covers everything: data sources, fiscal-year handling, sorting behavior, return format (paired data + citations), and efficiency improvement over sequential lookups. No output schema exists, but the return format is adequately described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by clarifying enum values ('company' pulls financials, 'drug' pulls FAERS data) and providing examples for the values array (tickers/CIKs for company, names for drug). This is helpful but schema already covers the basics.

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 specific verbs and resources: 'side-by-side comparison of 2–5 companies or drugs'. It includes example queries like 'compare X and Y' and distinguishes itself from sequential single-pack lookups, making the purpose unmistakable.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear usage context. It implies when not to use (single entity queries) but does not name alternative sibling tools explicitly.

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

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

Beyond the read-only/idempotent annotations, the description discloses account and paid-tier requirements, expected latency ranges, multi-hop gap recovery, contradiction scanning, semantic excerpting of large records, and a guarantee that citations are always fetchable. It also states that gaps are explicitly returned and that findings are 'never invented'.

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 every sentence carries substantive information: auth, alternatives, scope, output format, depth behavior, citation guarantees, and latency. It is mostly front-loaded, though the depth-iteration details are densely packed and follow the alternative-routing guidance in a way that makes the flow slightly less crisp.

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 values, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers latency expectations and multi-hop behavior, making the tool's behavior predictable enough for an agent 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 baseline is 3. The description adds useful examples for the question parameter and repeats/elaborates depth behavior, but it does not materially add new parameter semantics beyond what the schema already documents for `question` and `depth`.

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 and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in 'ONE call', and explicitly says 'this is NOT open-web search'. It also distinguishes the tool from siblings by describing how it decomposes questions, routes facets in parallel, and returns a findings packet.

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 clear when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, and explicitly routes simple lookups to 'ask_pipeworx instead'. It also adds an auth-based routing rule: 'If you are not signed in, use ask_pipeworx instead — it works on every tier.'

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it returns layer id+name and explains the optional service parameter behavior, going beyond annotations with actionable detail.

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

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

Two sentences, front-loaded with the core function. No extraneous information; every word contributes to understanding how to use the tool.

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

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

Given the tool's simplicity (one optional param, read-only) and lack of output schema, the description adequately covers input, output, and relationship to detroit_query. 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?

With 100% schema coverage, baseline is 3. The description adds value by clarifying the parameter's dual role (short name vs. full path) and the effect of omitting it, enhancing the schema's description.

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

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

The description clearly states the tool lists layers of a Detroit ArcGIS service for discovery. It distinguishes itself from sibling tools like detroit_query (which uses the returned ids) and detroit_recent by specifying its role as a discovery tool.

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

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

Provides explicit usage context: pass a short name or full path, omit to list known services, and use the returned id+name with detroit_query. Could be improved by stating when not to use it, but the guidance 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 mark it as read-only, idempotent, and non-destructive. Description adds specific behavioral detail: 'Epoch dates are converted to ISO.' No contradictions, but could mention defaults (like max limit 2000) which are in schema but not in description. Still adds value beyond annotations.

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

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

Two sentences, no redundancy. First sentence clearly states core function. Second provides essential usage guidance and a specific behavior note. 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 complex query tool with 6 parameters and no output schema, the description covers the core query verbs, date conversion, and guidance to sibling tools. Could mention result format or pagination hints, but schema covers limits. Overall fairly complete.

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

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

Input schema covers all 6 parameters with descriptions (100% coverage), so baseline is 3. Description adds context by summarizing the key parameters ('where, out_fields, order_by, limit') and mentions epoch date conversion, which is not in schema. Provides meaningful semantic addition.

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 queries Detroit ArcGIS layers by service path and layer ID, with full ArcGIS query parameters. Distinguishes from sibling tools detroit_layers and detroit_recent by directing users to them for finding 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?

Explicitly recommends using detroit_layers to find service/layer IDs and detroit_recent for common ones. Implicitly indicates when to use this tool (when you need to query data) and when to use alternatives (to discover layers), but lacks explicit 'when not to use' statements.

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 denote read-only, idempotent, non-destructive behavior. The description adds valuable context: returns newest rows first and converts ArcGIS epoch dates to ISO format. 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?

Three concise sentences front-load the purpose and usage guidelines, with examples and alternatives. No unnecessary text.

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 read tool with an enum and two optional parameters, the description covers purpose, usage, alternatives, return order, and date conversion. No output schema is needed given the simplicity.

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 parameters with descriptions (100% coverage). The description reinforces usage through examples and notes the ArcGIS SQL nature of the 'where' parameter, adding practical context beyond the schema.

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

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

The description clearly states the tool retrieves recent records from a specific Detroit open dataset by friendly name, avoiding the need for service IDs. It includes concrete use cases (crime, 311) and distinguishes it from sibling tools like detroit_layers and detroit_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?

Explicitly suggests preferring this tool over web search for common queries like 'recent crime in Detroit' and directs users to detroit_layers + detroit_query for other layers. Provides clear when-to-use and when-not-to-use guidance.

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

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

Description goes beyond annotations by detailing that results include full input schemas with curated examples and are ready to call directly, enhancing transparency. 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?

Description is reasonably concise with key information front-loaded. Lists examples and domains without excessive verbosity. A few words could be trimmed, but it remains efficient.

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

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

For a discovery tool with no output schema, the description fully explains what is returned (top-N relevant tools with schemas) and how to use them. Covers input, output, and usage context 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?

Input schema has 100% coverage with descriptions for all parameters, including aliases. The description reiterates the 'query' parameter as natural language but adds no further semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Find tools by describing the data or task' and lists numerous domains, differentiating it from sibling tools which are specific actions. It explicitly says to call this tool first when many tools are available, establishing its unique role.

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 guidance on when to use ('need to browse, search, look up, or discover what tools exist') and when to call first. Lacks explicit when-not-to-use, but the context is clear enough for an AI agent.

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

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

The description goes far beyond the annotations by disclosing the parallel fan-out across sources, soft-failure behavior for USPTO patents, the meaning of empty sections ('not a failure'), resolved:false behavior for private companies, and the presence of sources_used/sources_failed. This gives an agent an unusually complete and honest model of how the tool behaves and what could go wrong.

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

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

The description is front-loaded with the purpose and usage directive, then packs in a lot of necessary behavioral detail. It is long and dense, but most sentences earn their place because there is no output schema to carry the return-value documentation. Minor redundancy exists with the schema, but the structure is acceptable for a tool of this 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?

For a multi-source, complex tool with no output schema, the description is remarkably complete: it covers accepted inputs, every returned field area, source names, failure/soft-fail behavior, empty-section semantics, and private-company handling. An agent can confidently call this tool and interpret its responses without additional 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?

Although the schema already covers both parameters at 100%, the description adds crucial semantic nuance: 'type' accepts company or ticker interchangeably, 'value' can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR's company-name match. It also clarifies the private-company failure mode. This materially helps an agent construct a valid call.

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 precise statement: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource (US public company) and the specific action (profile across sources), leaving no ambiguity about what the tool does. It is also visually distinct from siblings like compare_entities and resolve_entity by its holistic, multi-source scope.

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

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

The description explicitly says to 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when the user wants a holistic view, which provides clear usage context and an alternative. It does not explicitly compare against siblings like deep_research or compare_entities, so the guidance is clear but not exhaustive about 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?

Description says 'Delete' which matches destructiveHint=true. It adds context about clearing sensitive data, but annotations already declare destructive and readOnly hints. No additional behavioral details 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 sentences, front-loaded with purpose. Every sentence adds value: purpose, usage guidelines, related tools. 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 1 parameter, no output schema, and full annotation coverage, the description provides sufficient context including purpose, usage guidelines, and sibling references.

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?

Single parameter 'key' with schema description 'Memory key to delete'. Description does not add further semantic meaning. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb, resource, and method. It distinguishes from siblings 'remember' and 'recall' which are explicitly mentioned.

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: 'when context is stale, task is done, or clear sensitive data'. Also mentions pairing with 'remember' and 'recall' as 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 readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which are consistent. The description adds that it fetches the page, extracts title/description/key links, and outputs markdown, giving behavioral context beyond annotations.

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

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

The description is concise: two sentences and a list of use cases. No fluff, every sentence adds value. Information is front-loaded with the main purpose.

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

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

With 2 simple parameters, no output schema, and full annotations, the description covers input, process, output format, and use cases adequately. It is complete enough for an agent to understand and 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema for parameters; it only mentions default and max for max_links implicitly. No additional parameter context is provided.

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 'generate' and the resource 'production-ready llms.txt file for any URL'. It also specifies the output format and use cases, making it distinct from sibling tools.

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

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

The description provides explicit use cases like getting a client's site indexed, drafting for own project, or auditing competitors. While it doesn't mention when not to use or alternatives, the examples are clear enough for an AI agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. Description adds that it returns specific fields (id, type, etc.) and implies user-specific scoping. No contradictions.

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

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

Two concise sentences with no fluff. Key information is front-loaded: what it does, what it returns, and 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 no output schema, the description lists return fields. Parameter is well-documented in schema. The tool is simple and the description fully equips an agent to use it correctly within the sibling 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?

Schema covers the single parameter with 100% coverage. Description mentions 'active subscriptions' which aligns with the default behavior of the include_inactive parameter, adding context 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 tool lists the caller's active subscriptions. Distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading existing 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?

Explicitly advises using this tool to review subscriptions before adding more or to find an id to cancel, providing clear when-to-use guidance.

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

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

With all annotations false, the description carries the full burden and does not disappoint. It discloses the claim_token mechanism (submit anonymously, later retrieve status/changes), rate limiting (5/day/identifier), cost (free, no quota impact), and the human review process (daily digests, roadmap impact). No annotation contradiction exists.

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 typical, but every sentence adds value: purpose, usage scenarios, exclusions, message tips, claim_token behavior, rate limits, and quota impact. It is front-loaded with the core purpose and uses compact phrasing. A 5 would require even tighter wording, but the density is justified given the tool's nuanced behavior.

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

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

The tool has no output schema and all annotations are false, so the description must cover behavior, limits, and invocation nuances. It does so comprehensively: what to report, how to frame it, when not to use it, what to expect (claim_token), and operational constraints (rate limit, quota). This is complete for an agent to decide and 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?

Schema coverage is 100%, so the baseline is 3; the description adds extra meaning beyond the schema. It explains how to use claim_token (pass it back alone to read a previous report), and gives message guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). While the schema already documents parameters, these context-rich instructions justify a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly differentiates the tool from sibling research/query tools by establishing it as the feedback channel for Pipeworx tooling. It also enumerates feedback types (bug, feature/data_gap, praise), making the purpose unmistakable.

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

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

The description provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and an explicit when-not-to-use rule: only for tools served by this Pipeworx connection, with a clear instruction to file elsewhere if the tool came from a different MCP server. It even offers a disambiguation heuristic ('Pipeworx tool names are the ones this connection lists'). This exceeds basic guidance by naming alternatives and 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?

The description adds behavioral context beyond annotations by specifying data source (CF analytics-engine), privacy (no PII), caching duration (5min-1h), and that the data is self-aggregating. 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 concise (three sentences plus a numbered list) and front-loaded with the core purpose. It could be slightly more structured, but every sentence provides necessary information.

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

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

Given the tool's simplicity (one optional param, no output schema), the description is complete: it explains what is returned (top tools, packs, volume), the source, caching behavior, and use cases. No significant gaps.

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

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

The single parameter 'window' is fully covered by schema (enum and description). The description adds value by explaining that shorter windows surface what's hot right now and longer windows show steady-state demand.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, distinguishing itself from siblings like 'discover_tools' by focusing on what other AI agents are calling on Pipeworx.

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

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

The description lists three specific use cases (discovering hot data sources, confirming popular tool, seeing alignment), which provide clear guidance on when to use the tool, though it does not explicitly mention when not to use it or alternatives.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds rich behavioral details: partition_sum check, Jaccard similarity threshold ≥0.30, placeholder filtering, fill check against CLOB depth, and conditions for not trading. 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 lengthy and dense, containing multiple paragraphs and many technical details. While well-structured with sections for each mode and key concepts, it could be more concise to improve readability for an AI agent. Every sentence adds value, but the verbosity may hinder quick parsing.

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 lack of an output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill_check details). It covers invocation behavior, edge cases (placeholder filtering, low similarity), and references an alternative tool. All necessary context for an agent to use the tool correctly is present.

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 parameter descriptions. The description adds significant value by explaining that event mode accepts slugs or full URLs, and topic mode uses a seed question for cross-event scanning, providing concrete examples. This is essential context not present 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?

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three distinct invocation modes (no args, event, topic) and explains what each does, distinguishing it from siblings.

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

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

Explicit guidance on when to use each mode is provided (e.g., 'call with NO args for a trending_scan', 'pass `event` for the strongest per-event partition_check'). It also explains the benefit of cross-event mode and references an alternative tool (polymarket_fill_risk) for custom sizing. Lacks explicit 'when not to use' comparisons to sibling tools like polymarket_edges.

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. Description adds extensive behavioral context: caching, segments, diagnostics, edge calculation, knob effects, and model details. No contradiction.

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

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

Description is long but well-structured with section headers and front-loaded purpose. Every sentence adds value, though some details (like model families) could be condensed 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?

Given 9 optional parameters and no output schema, description compensates by explaining response structure (by_segment, diagnostics) and edge components. Provides enough context for an agent to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. Description adds extra context for parameters like slippage, min_partition_leg_kelly, and tradeable-edge knobs, clarifying intent beyond schema.

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

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

Description clearly states it scans Polymarket markets for price discrepancies using Pipeworx data, with three specific segments. Distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on model-driven and structural arbitrage opportunities.

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 'what should I bet on today' and describes knobs for filtering, but lacks explicit when-not-to-use or direct comparison to siblings. Guidance is comprehensive for its purpose.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral details: it uses daily snapshots, returns time-series (tracked[] with full edge_pp_net series, first_seen, trend, decay_pp_per_day), expired opportunities, and snapshot dates. It also notes history depth is bounded by 60-day TTL and decay from daily closes. This goes well beyond the annotations.

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

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

The description is well-structured: it starts with a clear purpose, then details response fields and limitations. Every sentence adds value, though it is somewhat lengthy. It front-loads the key question being answered. A slight trim could improve conciseness, but it remains clear.

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

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

Despite no output schema, the description thoroughly explains the response structure: tracked[] with full time-series, first_seen, trend, decay; expired[] with lifespan; and snapshot_dates[]. It also covers limitations (60-day TTL, decay from daily closes). For a tool with 2 optional parameters, this is very complete.

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

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

Schema coverage is 100%, so both parameters are documented. The description adds meaningful context: for 'days', it reinforces default 14 and max 30, and ties it to lookback; for 'window', it explains it's a 'snapshot family' and gives examples. This enhances understanding beyond the raw schema.

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

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

The description clearly states the tool's purpose: answering how long an edge has existed and whether it is shrinking. It distinguishes a fresh wide edge from a 3-week-old wide edge, implying the tool provides temporal context. This differentiates it from siblings like polymarket_edges which likely give current edges without historical tracking.

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

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

The description provides clear context for when to use the tool: when edge persistence and decay telemetry are needed. It contrasts with polymarket_edges by focusing on historical snapshots. However, it does not explicitly state when NOT to use it or list alternative tools for other scenarios.

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

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

Adds significant behavioral context beyond annotations: describes ladder walking, return fields, risk of partial fills. Annotations already indicate read-only, non-destructive, idempotent; description aligns and enriches. Minor schema discrepancy (description says 'requires' but schema shows no required params) is not a 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 well-structured with headings (SINGLE-MARKET, BASKET) and bold key terms. Every sentence adds value; front-loaded purpose. Could be slightly shortened but acceptable given complexity.

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

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

No output schema, so description fully explains return values for both modes (e.g., top_of_book, vwap, capture_ratio, profit, thin_legs, forced_directional_risk). Covers risks and edge cases. Complete for a complex financial 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 100% parameter descriptions. Description adds crucial context: default values, mode-specific behavior, meaning of 'auto' for side, and interpretation of size_usd in basket mode. Complements schema well.

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 checks realizable-vs-theoretical edge against live order-book depth, explains two modes (single-market and basket), and explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by telling when to use it.

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 (before acting on arbitrage signals or trades above ~$500) and when not to (avoid partial fills that convert arb into directional position). Provides clear scenarios and warnings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive, so the bar for additional disclosure is high. The description goes far beyond: it explains the token-overlap matcher, the meanings of every compatibility code, when legs are never paired, the fee asymmetry (gross vs net spreads), and that unverified pairings are always possible. This is exemplary transparency.

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

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

The description is long but densely packed with necessary capability disclosure, structured by labels (TWO MODES, RESPONSE, SAFETY FIELDS, Codes, etc.). It front-loads the core purpose and carries a meaningful closing caveat. It loses one point because some information is repeated (e.g., temporal_alignment explained both as a code and in prose), though nothing is outright wasteful.

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 this tool has no output schema, the description must fully convey return structures and edge cases, and it does: leg prices, top_spreads_pp, flags[], skipped counters, temporal_alignment, and fees_note are all named with semantics. It also covers rare-result behavior and the meaning of null alignment. An agent has everything needed to interpret the response correctly.

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

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

The schema already has 100% coverage for all three parameters with examples and override semantics, which sets a strong baseline. The description adds the crucial mode-level meaning: how topic maps to auto-fetch, how the explicit parameters override the mapped side, and that both modes run the identical matcher. It enriches the bare parameter list with real invocation context.

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

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

The opening sentence names the exact resource and action: the cross-venue spread between Kalshi and Polymarket for the same resolving question. It further differentiates from potential siblings by distinguishing the macro-shortcut mode from explicit pairing, and by emphasizing that this is a signal tool, not a net-tradeable-edge calculator. No ambiguity about what it computes.

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 lays out two invocation modes ('topic' shortcuts vs explicit ticker/slug) and when to use each, including that explicit mode is for custom pairings. It also warns when not to rely on pre-mapped topics ('pre-mapped ≠ tradeable') and instructs users to read compatibility fields even when matched_pairs>0. This is direct when/when-not guidance.

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

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

Adds behavioral details beyond annotations: scoping to identifier, listing behavior when key omitted. Annotations readOnlyHint, idempotentHint, destructiveHint are consistent. No contradiction.

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

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

Two sentences, front-loaded, every sentence adds value. No wasted words.

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

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

Complete for a simple retrieval tool with one optional parameter; covers purpose, usage, scoping, and related tools.

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

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

Schema covers the parameter with description, but the description adds context about the correlation between omitting key and listing all keys, enhancing understanding.

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

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

Clear verb 'retrieve' with specific resource (saved memories) and explicit distinction from siblings 'remember' and 'forget'.

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

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

Describes when to use ('look up context stored earlier'), mentions scoping and pairing, but lacks explicit 'when not to use' statements.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds mark_read side effect but doesn't clarify potential non-idempotency. No mention of auth or rate limits.

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

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

Three sentences, front-loaded with purpose, efficient with no wasted words. Structure is clear and focused.

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 return fields, filtering, mark_read side effect, and alternative endpoint. For a read-only tool with 5 optional params and no output schema, this is complete.

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

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

100% schema coverage with descriptions; description re-iterates with example for type and ISO timestamp, adding marginal value.

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

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

Description clearly states it pulls fired events from subscription feed and returns recent alerts with specific fields. Distinguishes from siblings like 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?

Provides guidance on filtering by type and since, setting mark_read for state management, and mentions polling and alternative endpoint. Lacks explicit exclusions but covers usage well.

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, soft-fail for USPTO, and return structure (changes[], total_changes, citation URIs). Annotations already indicate read-only, idempotent, non-destructive, and open-world; description adds substantial behavioral context without contradiction.

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

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

Single paragraph that front-loads query examples and then details behavior. Every sentence contributes useful information; no redundancy. Could benefit from slight structuring (e.g., bullet points) but remains efficient.

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

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

Despite no output schema, the description fully explains return values and behavior. It covers multi-source behavior, fallback, soft-fail, time window formats, and cross-reference to sibling tool. Given tool complexity, this is complete.

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

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

Schema coverage is 100% but description still adds value by explaining accepted date formats ('2026-04-01', '7d', '30d'), recommending typical values ('30d' or '1m'), and providing examples for value (ticker or CIK). This exceeds baseline 3.

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

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

The description clearly states the tool provides a change feed for a company, listing specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes from sibling tool entity_profile for static profiles.

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

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

Includes explicit guidance on when to use this tool vs. alternatives — 'Use entity_profile instead when you want the static profile...' — and provides concrete example queries. Also explains fallback behavior between GDELT and GNews.

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

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

The description adds significant behavioral context beyond annotations: key-value pair scoped by identifier, persistence duration (24 hours for anonymous, persistent for authenticated). 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 efficient at 4 sentences, front-loaded with the core purpose, followed by usage and technical details. Every sentence serves a purpose without redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description covers all necessary aspects: purpose, when to use, technical behavior (scope, persistence), and relationships to sibling tools. No gaps.

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

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

Schema coverage is 100%, but the description enhances meaning with example keys (e.g., 'subject_property', 'target_ticker') and clarifies the value as 'any text — findings, addresses, preferences, notes', adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and provides specific examples of what to store (resolved ticker, target address, etc.). It distinguishes from sibling tools like recall and forget.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and mentions pairing with recall and forget. While it doesn't include an explicit when-not-to-use, it gives strong contextual guidance for usage.

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 readOnly/openWorld/idempotent annotations, it discloses cascading internal lookups, graceful degradation if GLEIF/OpenFIGI are unavailable, explicit `unresolved` identifiers, and `figi_candidates` for ambiguous matches. This is substantial behavioral context not visible in the annotations or schema, and nothing contradicts the annotations.

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

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

The description is front-loaded with examples and a direct usage rule, and nearly every clause carries needed detail for a complex resolver. It is dense and occasionally run-on, so it could be tightened, but the length is largely justified by the number of edge cases it must convey.

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

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

There is no output schema, yet the description covers what is returned for company (CIK/ticker/LEI/FIGI/ownership), drug (RxCUI/ingredient/brand/citation), the ambiguity path (`figi_candidates`), and the `unresolved` field. It also specifies graceful failure behavior and input constraints, so an agent has enough 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?

Although schema coverage is 100%, the description adds critical semantics: accepted input forms (ticker, CIK, ISIN, name; brand/generic), the exact caveat to pass only the entity name and not trailing security-class words for bonds, and the behavior for ambiguous names. This materially reduces the risk of mis-calling the tool.

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 ('resolve a user-spoken NAME to canonical/official identifiers'), provides concrete example queries ('What's the ticker for…'), and enumerates supported entity types (company vs drug). It also distinguishes itself from sibling tools by framing the output as IDs that other tools require as input.

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 directs 'Use FIRST whenever you have a name but need an ID' and clarifies when company vs drug applies, including input forms like ISIN-to-LEI. It does not name alternative tools or state explicit exclusion conditions, but the directive plus supported-type detail gives strong contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, making the tool's safety profile clear. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. 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 two sentences long, front-loading the primary function in the first sentence and adding a concrete use case and example in the second. Every sentence is value-adding, 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?

Given the tool has 4 parameters and no output schema, the description adequately explains the core behavior (probing, ranking, returning metrics) and the use case. It does not elaborate on output structure or limitations (e.g., model support), but the combination of high purpose clarity, parameter coverage, and annotations makes it sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by clarifying that the first entity in the array is treated as the 'subject' for narrative purposes, while the rest are competitors. This additional semantic context raises the score.

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 ('Compare') and resource ('AI visibility across multiple entities'), and clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI visibility ranking.

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 a clear use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when not to use it or mention alternatives. However, the sibling context implies that ai_visibility_check is for single entities, so guidance is satisfactory but not fully explicit.

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

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

Beyond annotations (readOnly, idempotent), describes partial failure handling, timing (5-30s for bundlephobia first measurement), and graceful degradation with sources_failed field.

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 comprehensive but front-loaded with purpose. Every sentence provides useful detail, though length could be slightly reduced 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?

No output schema, but description fully enumerates return fields (summary, advisory detail, links, alternatives) and covers edge cases (failure modes, ecosystem scope).

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

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

Schema already covers both parameters with descriptions. The description adds context: scoped packages accepted and default version behavior, providing marginal extra value.

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

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

The description explicitly states the tool performs a composite check for npm packages across deps.dev and bundlephobia, answering 'should I add this npm package to my project'. It distinguishes from handling other ecosystems directly via deps.dev.

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 guides when to use: 'whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also provides alternative for non-NPM packages.

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

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

Adds significant behavioral details beyond annotations: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation, and character offsets for verification. Fully consistent with readOnlyHint, idempotentHint.

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

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

Single paragraph, front-loaded with purpose. Slightly dense but every sentence adds value. Could be split for readability but remains efficient.

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

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

Given no output schema and 3 parameters, the description covers purpose, usage, behavioral traits, and parameter examples. Mentions output format (passages with offsets and scores), completing the 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?

Schema coverage is 100% (baseline 3). Description adds examples for query parameter and clarifies text is 'already pulled record.' Provides context for max length of text.

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 'Semantic search INSIDE a fetched record,' specifying verb and resource. Distinguishes from siblings by explicitly naming ask_pipeworx_grounded as a complementary tool.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt.' Mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not scenarios but provides clear context.

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

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

The description states that each call creates a new subscription and returns a new ID, implying non-idempotent behavior. However, annotations include idempotentHint=true, which contradicts this. According to the scoring rules, this contradiction results in a score of 1.

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 informative, with a clear purpose statement followed by requirements, type examples, and delivery details. Slightly verbose but 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 no output schema, the description explains the return value (subscription ID) and covers prerequisites, type-specific params, and delivery constraints. It lacks error handling information but is otherwise complete for agent usage.

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

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

Schema coverage is 100%, and the description adds significant detail beyond the schema, including type-specific parameter examples, constraints (SMS cap, phone verification, webhook signing), and explanations of optional delivery channels.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return of a new subscription ID. It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description explains when to use the tool (proactive monitoring), lists requirements (Pipeworx OAuth account), and details supported types with examples. It implicitly contrasts with other alert-related tools but does not explicitly compare 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, idempotent, non-destructive. The description adds that return includes category-bucketed example questions with tool+argument shapes, drawn from live catalog, and that calling with no arguments gives full spread. This provides useful behavioral context beyond annotations.

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

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

The description is relatively long but well-structured, starting with common queries, then purpose, return format, and usage. Every sentence adds value, though some redundancy could be trimmed. Overall, it's organized and front-loaded with key info.

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 purpose as an onboarding entry point, the description is fully complete. It explains what it returns, how to call it (with or without topic), and when to use it. No output schema is needed for this exploration 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 adds value by listing possible topic values (finance, pharma, etc.) and clarifying that omitting gives a cross-category spread, which is more helpful than the schema's brief description 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 returns category-bucketed example questions with exact tool and argument shapes, and explicitly positions it as the onboarding entry point. It distinguishes from siblings like ask_pipeworx by noting it's for exploring what the system can do, not for asking direct 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?

The description 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. It doesn't explicitly list exclusions, but the context makes it clear this is for exploration and not for getting direct answers.

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 ownership enforcement and deactivation (not deletion), adding value beyond annotations. Annotations (readOnlyHint false, destructiveHint false, idempotentHint true) align with description, no contradictions.

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

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

Two sentences, front-loaded with the action, no waste. Every sentence adds essential 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?

Adequate for a simple tool with one parameter and no output schema; covers purpose, behavior, and relationship to sibling tools. Could mention the success response, but not critical.

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

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

With 100% schema coverage, the description adds that 'id' comes from 'subscribe', which is extra context beyond the schema's description of 'Subscription id (uuid) returned by subscribe.'

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'), and distinguishes itself from siblings by noting ownership enforcement and deactivation behavior, referencing 'recent_alerts' for historical data.

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

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

Clearly states when to use (cancel subscription by id) and an important constraint (ownership enforcement). Does not explicitly list alternatives or when not to use, 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?

Adds significant behavioral detail beyond annotations: it explains verdict types, the crucial meaning of could_not_verify (not evidence), the unsupported verdict, the grounded pipeline routing, and the use of verbatim evidence. It also notes the tool is a single-call replacement for a multi-step pipeline. No contradiction with the readOnly/idempotent 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 well-structured: starts with query examples, then usage guidance, routing logic, return values, and error semantics. It is longer than average but every sentence contributes useful context. Slightly verbose, but organized logically.

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 remarkably complete. It covers scope, routing, verdict semantics, error handling, and performance benefits. It even clarifies how to interpret ambiguous verdicts, making it self-contained and trustworthy for an agent.

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

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

Both parameters are already documented exhaustively in the input schema (100% coverage), including examples and tolerance_pct semantics. The tool description does not add parameter-specific meaning beyond what the schema provides, so it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources.' It provides example query phrasings and explicitly distinguishes itself by noting it replaces 4–6 sequential calls for the same task. This differentiates it from sibling research tools.

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

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

Gives an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details routing for financial vs. other claims, but doesn't name alternative tools or state explicit exclusions. Still, the context is clear and practical.

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