California DMV

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

Annotations declare read-only, idempotent, non-destructive. The description adds details on default model (free), Anthropic probing (BYO key, direct payment), and return structure (per-model score/confidence/signals/raw_response + combined view). 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?

Four sentences, front-loaded with core action, no wasted words. Each sentence adds distinct value (what it does, default, optional, output, use cases).

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 covers return format. Parameters are fully described in schema and description adds extra context. Lacks mention of error handling or rate limits, but overall adequate for the tool's 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 coverage is 100%, but the description adds value by explaining _apiKey cost implications and context parameter's disambiguation role. This goes beyond raw schema descriptions.

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

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

The description clearly states the tool probes LLMs to score visibility (0-100) per model, with default model and optional Anthropic probing. It distinguishes from siblings like entity_profile or scan_competitor_ai_presence by focusing on AI visibility metrics.

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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly exclude any scenarios or compare with sibling tools, but the context is clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds genuinely useful behavior: it routes to one of 5,767 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict any annotation.

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

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

The description is front-loaded with the key directive and supported by relevant examples, but it is noticeably long and contains a malformed/truncated sentence around 'except for questions requiring...'. Several ideas are repeated, such as factual coverage and triggers, which hurts conciseness.

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

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

Given no output schema, the description still tells the agent what it returns: a structured answer with citation URIs. It also covers supported data domains, trigger phrases, alternatives, and example queries. The main gaps are failure/edge-case behavior and the unclear exception clause, but overall the agent has enough to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds example queries and clarifies the expected natural-language format, but it does not add new parameter-level semantics beyond what the input schema already documents for 'question' and its aliases.

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 and resource: ask a natural-language factual question and get a routed, citation-backed answer from a large set of verified sources. It distinguishes itself from web search and sibling tools by explicitly stating its scope: SEC, FDA, FRED/BLS, patents, real estate, news, stocks, and more. Examples reinforce the purpose without ambiguity.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual questions, including trigger phrases and six concrete examples. It also names alternatives like ask_pipeworx_grounded and deep_research, though one transition is garbled ('except for questions requiring...'), making the when-not guidance slightly incomplete.

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 read-only, idempotent, non-destructive behavior, and the description adds meaningful real-world context: no candidate is currently active, so it matches ask_pipeworx exactly; candidates may alter routing live; results feed merge decisions; and it is a full router with no fallback. This transparently sets expectations about variability and current status.

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 core identity and conveys essential status, usage, and caveats in a compact block. Some redundancy exists between 'Beta version' and 'experimental edge,' but every sentence contributes useful information such as the active-candidate status and fallback semantics.

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 router with six aliased parameters, no output schema, and safety fully covered by annotations, the description provides sufficient context: current behavior, relationship to ask_pipeworx, response shape consistency, and routing philosophy. It does not define the actual response shape or tool list, but references ask_pipeworx as the source of that detail, which is acceptable given 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 coverage is 100%, so the input schema already documents the aliases and required question parameter. The description only mentions 'same arguments' as ask_pipeworx, which adds no semantic detail beyond what the schema provides, justifying the baseline 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 identifies the tool as a beta version of ask_pipeworx and a universal router with the same tools, arguments, and response shape, making its role clear. It distinguishes itself from ask_pipeworx by the experimental routing improvements, though it relies on the sibling's definition for what the router actually does rather than stating it directly.

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 wanting the newest routing, and contrasts it with the stable router whose results are used for comparison. This gives concrete when-to-use guidance and implies ask_pipeworx as the stable alternative, though it does not discuss when to prefer ask_pipeworx_grounded.

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, openWorldHint, and non-destructive behavior, so the description only needs to add context beyond those. It adds the refusal contract with specific refusal_reason values, the success response shape with verbatim evidence, and the extra LLM call cost. There is no contradiction between the description and 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 dense but well-structured: tagline, routing mechanics, return contract, refusal reasons, usage guidance, and cost trade-off are all packed into three efficient sentences. Every sentence earns its place, and the most important differentiator is front-loaded.

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

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

Even though there is no output schema, the description explicitly enumerates the success response shape, the refusal response shape, and all refusal_reason values. It also covers routing behavior, latency cost, and when to choose the sibling tool, so an agent has everything it needs to invoke this tool correctly.

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

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

Schema coverage is 100%, with the question parameter fully documented including aliases, so the baseline of 3 applies. The description adds context that the tool performs routing and argument-filling internally, which is useful, but it does not add new syntax, constraints, or meaning for the parameter beyond what the schema already provides.

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

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

The description opens with the specific verb phrase 'Hallucination-resistant answer mode' and clearly identifies the resource: high-stakes reads with grounded, evidence-backed answers. It distinguishes itself from the sibling ask_pipeworx by emphasizing extraction from tool results only, verbatim evidence, and explicit refusals. This is a precise and differentiated definition.

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 criteria: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains such as financial verdicts, legal claims, and medical lookups. It also names the alternative and the condition for preferring it: 'prefer ask_pipeworx for casual lookups.' This fully answers when-to-use versus when-not-to-use.

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

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

The description extensively covers behavioral traits beyond annotations: low-confidence resolution short-circuits, closed market handling, wide-spread tradeability warnings, cancellation rule parsing, and fan-out behavior. No contradiction with annotations (readOnlyHint, etc.). All critical behaviors are disclosed.

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

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

The description is lengthy but well-organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), making it scannable. The main purpose is front-loaded. A minor deduction for verbosity, but structure mitigates 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 comprehensively explains the response structure: market fields, analysis with model probability and edge, evidence keys, resolver contract, parent event extractor, news fields with fallback info, and safety mechanisms. It leaves no significant gaps for an agent to understand inputs and outputs.

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 meaning: explains market parameter formats with examples, depth parameter with 'quick' vs 'thorough' semantics, and include_raw with size implications. This enhances understanding beyond the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the exact input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). While it doesn't explicitly differentiate from sibling tools, its unique purpose is 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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives detailed fan-out examples for various bet categories. However, it doesn't mention when not to use this tool or alternatives among siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds that it is an annual series from 2008 and counts people, not vehicles, providing useful context beyond annotations.

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

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

Three sentences: purpose, examples, and distinction. No wasted words, 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?

For a simple counting tool with good annotations and parameter descriptions, the description is nearly complete. It could mention return value format but the input schema examples implicitly cover that.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description does not add new parameter-level information but hints at filtering by county and year. Baseline 3 is appropriate.

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

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

The description clearly states the tool counts driver licenses and IDs by county annually from 2008. It includes example questions and explicitly distinguishes from ca_dmv_vehicle_registrations, a sibling tool, using specific verb 'count' and resource.

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

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

The description gives explicit usage context: answers county-level licensed driver counts and directs to ca_dmv_vehicle_registrations for vehicle registration queries. It does not cover when NOT to use (e.g., for total state counts) but provides a clear alternative.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: snapshot years back to 2019, default year 2026, substring matching for make, and two distinct return formats. This goes beyond annotations, though authentication and rate limits are not mentioned.

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

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

The description is concise, front-loading the core purpose, then listing example queries and parameter details. Every sentence adds value with no redundancy.

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

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

With no output schema, the description adequately explains the two return types (fuel mix with shares or breakdown by dimension) and covers all parameters. It could be more explicit about response structure or pagination, but the examples cover common use cases.

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% description coverage with detailed parameter descriptions. The tool description reinforces this but does not add new semantic meaning beyond what the schema already provides. For example, the group_by parameter description in the schema already explains the options.

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 'measure' and the resource 'electric-vehicle adoption in California'. It provides specific examples of queries it answers, distinguishing it from sibling DMV tools that deal with driver licenses, forms, offices, etc.

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

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

The description lists example questions and mentions statewide or ZIP-code scope, giving clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternatives, though the narrowly defined domain makes this less critical.

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. Description adds that results follow the DMV site's own relevance ranking, providing extra 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?

Description is concise, front-loaded with the main action, and includes relevant examples. Every sentence adds value.

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

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

For a search tool with no output schema, the description adequately states what is returned (name, form number, download page). It also mentions relevance ranking and provides example use cases.

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. Description adds examples and clarifies the query parameter, but does not significantly extend beyond schema descriptions.

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

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

Description specifies 'Search the official California DMV forms catalog by topic and get each form's name, its REG/DL/BOAT form number, and the page to download it from.' It clearly differentiates from siblings like ca_dmv_driver_licenses and ca_dmv_vehicle_registrations by focusing on forms.

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 example queries and explains relevance ranking. However, it does not explicitly state when not to use this tool or mention alternatives beyond the context of siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, providing a clear safety profile. The description adds minimal behavioral context (e.g., that codes are national) but does not disclose additional traits like error handling or data source freshness.

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 that start with the core purpose, then provide usage examples and a clarifying note. Every sentence adds value with no redundancy.

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

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

For a simple lookup tool with one parameter and no output schema, the description covers the use case, data source, and typical queries. It could mention the return format explicitly but is adequate for agent understanding.

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 for the single parameter 'insurer' is 100%, with a clear description. The description reinforces the parameter usage with examples but adds no new semantic details 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 function: look up an auto insurer's NAIC code from the California DMV list by company name. It provides example queries and distinguishes from siblings like ca_dmv_driver_licenses by focusing on insurance codes.

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

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

The description implies use when needing an NAIC code for California DMV reporting, but does not explicitly state when not to use it or compare with other tools. No alternatives among siblings are mentioned.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context on data source ('DMV's own directory') and coverage ('all 187 field offices'). No contradictions; however, it could mention rate limits or authentication, but for a read-only tool, current detail is adequate.

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 (about 5 sentences), front-loaded with the core purpose, and every sentence adds value. No fluff or 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?

Although there is no output schema, the description explains the return type (address, opening hours, coordinates, services) and coverage (187 offices). This is sufficient for a query tool with well-documented parameters.

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

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

Schema coverage is 100% with all parameters described. The description goes beyond schema by listing example services ('behind-the-wheel retest, duplicate title, etc.'), which provides helpful hints for the service parameter.

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

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

The description clearly states the verb 'find' and resource 'California DMV field offices', and lists the information returned: address, opening hours, coordinates, and services. It distinguishes from siblings by noting that wait times are not available and pointing to alternative 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 example queries ('DMV office in Sacramento', 'which California DMV near San Jose does driving tests') and explicitly states when not to use it: for live wait times, California publishes none, and suggests siblings nc_dmv_wait_times and or_dmv_wait_times.

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

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

Annotations already indicate safe read operation. Description adds detail about data source, annual snapshots from 2019, and default year (2026), enhancing transparency beyond 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?

Description is three sentences, front-loaded with the main function, and contains no redundant information. Every sentence serves a 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?

Despite no output schema, the description explains each row's content, data source, and available snapshots. It also covers typical use cases and sibling tool boundaries, making it complete for agent understanding.

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 full descriptions. Description mentions key parameters but does not add significant new meaning beyond the schema. Baseline score of 3 applies.

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 counts registered vehicles by various dimensions (ZIP, make, etc.) and provides concrete example queries. It also distinguishes sibling tools like ca_dmv_ev_adoption and ca_dmv_offices.

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 specifies when to use (count queries) and explicitly advises using ca_dmv_ev_adoption for EV share and ca_dmv_offices for office addresses, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), sorting by primary metric, and citation URIs. 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 a single, dense paragraph that front-loads usage triggers and purpose. Every sentence adds value, though it could benefit from slight structural separation for readability.

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

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

Given no output schema, the description partially covers return format ('paired data + citation URIs') and sorting. It lacks a precise description of the output structure (e.g., side-by-side comparison fields for financials vs adverse events). For a tool with moderate complexity, this is adequate but not comprehensive.

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

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

Schema coverage is 100%. The description enriches both parameters: explains the type enum with specific data pulled for each value, and clarifies the values array with examples (tickers/CIKs for company, drug names for drug). Adds meaningful 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?

The description provides a specific verb ('compare'), resource ('companies or drugs'), and constraints ('2–5 entities in ONE parallel call') with natural language triggers. It clearly distinguishes from siblings like entity_profile by explicitly stating preference over sequential lookups.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and implies when not to (single entity). However, it does not name alternative tools like entity_profile for singular lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavior beyond this: account and paid-plan requirements, parallel decomposition across many tools, explicit gaps[] with never-invented evidence, hop semantics, contradictions[], fetchable citations, semantic excerpting, and expected latency. 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 long but dense and front-loaded with the most critical constraint (account required). Every sentence adds decision-relevant information: alternatives, scope, return shape, edge-case behavior, gaps, contradictions, latency. No filler or vague boilerplate.

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

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

Without an output schema, the description must explain what the agent will receive; it does, specifying the findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and citation_uri. It also covers prerequisites, latency, and when the tool will produce empty results. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by clarifying that depth:'thorough' requires a paid plan and by explaining the research-hop behavior in practical terms. It does not enumerate parameters again but enriches their operational meaning.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources in a single call. It clearly distinguishes itself from open-web search and from ask_pipeworx, explaining exactly what kind of questions it is for.

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

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

The description gives explicit when-to-use guidance: broad/multi-part questions over structured data. It also gives explicit when-not-to-use guidance and alternatives: single lookups and breaking/colloquial current news should use ask_pipeworx, and unsigned-in users should use ask_pipeworx. This is exemplary routing guidance.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, but the description adds useful behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' This explains the output behavior 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, front-loads the purpose, and then provides additional details. It is well-structured with no unnecessary words, though could be slightly more compact.

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

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

Despite no output schema, the description fully explains the return format (tool names, descriptions, input schemas, examples). It also covers when to use it first. All relevant aspects are addressed.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds semantic value by explaining that 'query' accepts aliases (task, q, description, search) and provides usage examples, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the resource (tools) and action (discover), and distinguishes itself from sibling tools that are specific data lookups or actions, making it a meta-discovery tool.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools...' This provides clear context for when to use, though it does not explicitly list when not to use or name specific 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 cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower.The description adds substantial runtime behavior beyond that: parallel fan-out across 8+ sources, source-specific soft-fail (USPTO PatentsView sunset), GDELT→GNews fallback, sources_used/sources_failed semantics, and resolved:false behavior for private companies. 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?

Excellently front-loaded with trigger phrases and the core purpose, and the overall structure (purpose → sources → returns → failure semantics → value shapes) is logical. However, it's a dense multi-clause paragraph that restates parameter semantics already present in the schema ('Pass a ticker...', 'type accepts company or ticker interchanngeably'), so not 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?

With no output schema, the description carries the return-value burden and does so well: it documents cik, company_name, resolved_from/to, recent_filings with pipeworx URIs, fundamentals fields, sources_used/sources_failed, and key failure behaviors. Minor gaps remain — the news section contents and full output shape aren't exhaustively enumerated — but for an 8-source fan-out tool this is largely complete.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description restates accepted value shapes (ticker, CIK, company name) and type interchangeability with little added meaning, though it does add that name inputs produce resolved_from/resolved_to fields. Baseline 3 is correct — the schema carries the load.

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

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

States a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call,' and opens with concrete trigger phrases ('Tell me about X', 'research Acme', 'brief me on Tesla'). Explicitly distinguishes itself from single-pack SEC/XBRL/news lookups, so an agent can tell it apart from narrower tools before inspecting schemas.

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

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

Gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also covers edge cases — private companies return resolved:false with a notes line, and empty sections are real 'no data' — so the agent knows both when to use it and what to expect when it won't fully succeed.

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and reinforcing the destructive nature, but does not introduce new behavioral traits beyond annotations.

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

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

Three sentences, no wasted words. The action and key detail are front-loaded, making it efficient to parse.

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

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

For a simple tool with one parameter, no output schema, and destructive behavior, the description fully covers what it does, when to use, and related 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%, and the schema describes 'key' as 'Memory key to delete'. The description only mentions 'by key' without adding meaning beyond the schema, so baseline 3 applies.

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?

Explicitly states 'Delete a previously stored memory by key', providing a specific verb and resource. Mentions pairing with remember and recall, distinguishing its function 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?

Clearly specifies when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with remember and recall, offering guidance on alternatives.

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

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

The description adds behavioral context beyond the annotations by explaining the fetch-extract-emit process. The annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description enriches these with specific actions.

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

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

The description is three sentences with no wasted words: first sentence states purpose, second summarizes process, third lists use cases. It is front-loaded and highly scannable.

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 2 well-documented params, comprehensive annotations, and no output schema, the description covers the core behavior and output format ('single text blob'). Minor omission: no mention of error handling or input validation, but adequate for a simple read-only tool.

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

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

The input schema has 100% description coverage for both parameters, so the description adds minimal value. It mentions 'any URL' and 'max 50' but does not elaborate beyond what the schema already provides.

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

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

The description states a specific verb ('generate') and resource ('llms.txt file for any URL'), and distinguishes itself from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing solely on generating the standard llms.txt file.

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 concrete use cases (client indexing, personal projects, competitor auditing), providing clear context. However, it does not explicitly state when not to use this tool or compare to alternative approaches.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying return fields (id, type, params, etc.) and default behavior (active only). Contradictions: none.

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

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

Two sentences with no waste: first sentence defines purpose and output, second sentence provides usage guidance. Front-loaded with key information.

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

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

For a simple tool with one optional parameter, good annotations, and no output schema, the description covers purpose, parameters, return values, and usage advice. 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% with one parameter fully described. The description adds 'active subscriptions' context, which is already implied by the parameter's default false. Baseline 3 is appropriate; marginal additional meaning.

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

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

The description clearly states the verb 'List' and the resource 'subscriptions', specifying it returns the caller's active subscriptions. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing rather than creating or canceling.

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 to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to invoke. It does not explicitly exclude alternative use cases, but the guidance is sufficient.

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

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

Annotations are minimal (all false), so the description carries full burden. It discloses the claim_token workflow (filing without account returns a token, passing it back reads status), rate limits (5 per identifier per day), cost (free, doesn't count against quota), and the team's digest review process. Also warns against pasting end-user prompts, adding behavioral nuance.

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 earns its place: purpose, use cases, exclusions, workflow, rate limits, and cost are all covered without redundancy. It is front-loaded with the main action and structured 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?

Despite no output schema, the description explains return behavior (claim_token and later status retrieval). It covers all 4 parameters, the nested context object, and the tool's operational constraints (rate limit, quota). The description is fully 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 coverage is 100%, so baseline is 3. The description adds value by advising 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which gives extra semantics for the message parameter beyond the schema's generic description. It also reinforces the claim_token usage context, though the schema already explains it.

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.' It enumerates concrete use cases (bug, feature, data_gap, praise) and clearly differentiates from sibling tools by limiting scope to Pipeworx-served tools only, explicitly excluding other MCP servers.

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

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

Provides explicit when-to-use triggers ('Use when a tool returns wrong/stale data...'), when-not-to-use ('if the tool came from a different MCP server... file with that server instead'), and an alternative action (file with that server). Also gives a heuristic for disambiguation: 'Pipeworx tool names are the ones this connection lists.'

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, non-destructive), the description adds key details: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h). Provides complete behavioral context.

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

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

Concise and well-structured: opens with purpose, lists usage contexts, describes derived nature. Every sentence adds value; no redundancy.

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

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

For a simple list with one optional parameter and no output schema, the description covers purpose, usage, data sourcing, caching, and privacy. 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?

Only one parameter with full enum in schema. Description adds semantic guidance on window choice (short = hot, long = steady-state), beyond the schema's basic description.

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

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

The description clearly states the tool returns top tools, packs, and call volume over configurable time windows. It distinguishes itself from siblings by specifying the returned data structure and temporal 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?

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, aligning use cases). Could be more explicit about when not to use, but the guidance is strong.

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

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

Description details behavioral traits beyond annotations: monotonicity violation detection, partition-sum checks, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholders), fill check using CLOB depth. It warns when the edge is not realizable (realizable_edge_pp ≤ 0). All behaviors align with annotations (readOnly, idempotent, openWorld, non-destructive).

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

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

The description is lengthy but well-structured: starts with core purpose, then explains modes in a logical order, then detailed algorithmic components, and ends with response format. Every part adds value, though some verbosity could be trimmed.

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 fully explains the response structure: opportunities[] with fields like gap_pp, suggested_trade, reasoning, and for event mode partition_check with sum_yes_prices, gap_from_1, etc. Also covers fill_check details and when not to trade. Complete for a tool of this complexity.

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

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

Schema covers 100% of parameters with descriptions. The description adds significant context: explains event slug vs topic seed question, gives examples, describes the effect of each mode, and clarifies that omitting both defaults to trending scan. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three invocation modes (default trending scan, event, topic) and names specific resources. Differentiates from siblings like polymarket_fill_risk by mentioning its use for custom sizing.

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

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

Explicit guidance is provided for each mode: default for trending scan of top ~200 markets by volume, event for a specific market slug, topic for cross-event scanning. It recommends event mode for specific markets and explains when cross-event mode is superior (catches patterns single-event misses). It also directs to polymarket_fill_risk for custom sizing.

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

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

The description adds extensive behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.), detailing three model segments, edge calculations, slippage, Kelly fractions, 24h move warnings, tradeable-edge filters, caching behavior, and diagnostic output. No contradictions with annotations.

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

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

The description is comprehensive but verbose, containing many details (e.g., exact tickers, gate values from a specific run). While well-structured with headings, it could be more concise for an AI agent's quick comprehension. Every sentence is valuable, but the length may hinder 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 complexity (9 parameters, no output schema), the description covers response structure (by_segment, fed_candidates, diagnostics) and tool behavior (caching, knobs). It lacks only explicit return value types and error handling, but with the level of detail, it is nearly 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% (all 9 parameters have descriptions). The tool description adds extra context for parameters like min_kelly (explains why it doesn't filter partition arbs) and slippage_pp (notes Polymarket's zero fees but bid/ask costs). This enriches understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on opportunity discovery without paging.

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 the tool is for discovering opportunities and provides usage context (e.g., knobs like min_liquidity, max_spread_pp). However, it does not explicitly compare with sibling tools or state when not to use it, leaving the agent to infer alternatives from names alone.

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

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

Annotations declare readOnly, idempotent, non-destructive. The description adds rich behavioral detail: response structure, decay computation, caveats about data gaps and limits, and interpretation of signed values.

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

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

The description is comprehensive but well-structured: front-loaded purpose, clear response format, and limits. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description fully explains return fields (tracked, expired, snapshot_dates) and handles edge cases (data gaps, trend calculation, signed values).

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

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

Input schema covers both parameters with descriptions. The description adds context (defaults, clamping, snapshot gaps) and clarifies the meaning of 'window' 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: edge persistence and decay telemetry. It answers the concrete question 'how long has this edge existed and is it shrinking?' and distinguishes from sibling tools like polymarket_edges.

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

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

The description implies usage for assessing edge duration and trend, and mentions limitations (60-day TTL, data gaps). It doesn't explicitly list alternatives or when not to use, but the context of sibling tools provides enough 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=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about the risk of partial basket fills converting an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is a single dense paragraph but is well-structured using all-caps keywords (REQUIRES, SINGLE-MARKET, BASKET) to guide the reader. It efficiently packs a lot of information without redundancy. Minor improvement could be splitting into clearer sections, but overall it is concise and front-loaded with the most critical information.

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

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

Given the tool's complexity (two modes, no output schema), the description comprehensively covers parameter requirements, defaults, return values for each mode, behavioral caveats, and the risk of directional exposure. It addresses the user's likely concerns (e.g., 'thin_legs[]', 'forced_directional_risk'). No gaps remain for the intended use case.

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

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

Schema description coverage is 100% (all parameters have descriptions), and the description adds additional meaning: it explains the distinction between `market` and `event` for single-market vs basket mode, interprets `size_usd` differently for each mode (spend vs settlement notional), and describes the default side logic for basket mode. This goes well beyond what the schema alone provides.

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

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

The description explicitly states the tool's purpose: a realizable-vs-theoretical edge check against live CLOB order-book depth. It clearly distinguishes two modes (single-market and basket) and lists specific return fields. It names sibling tools (polymarket_arbitrage, polymarket_edges) and explains how this tool relates to them, providing clear differentiation.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the rationale (theoretical overround not capturable on thin books, partial fills converting arb to directional risk) and states the requirement for exactly one of `market` or `event` to be provided.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses many operational behaviors: identical token-overlap matcher in both modes, compatibility_codes semantics, null-vs-unknown temporal alignment distinction, unclassified legs never paired, gross fees not net, and skipped cross-type/subtype counters. This far exceeds what the annotations convey.

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

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

The description is long, but it uses labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and the core purpose is in the first sentence, making it navigable. Each paragraph adds a distinct behavior or caution that matters for correct invocation; some redundancy exists, but for a tool with no output schema and zero required parameters, the length is justified.

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 and only sparse annotations, the description carries the full burden of explaining return values, and it does so thoroughly: spread fields, safety codes, per-entry flags, skipped leg counters, temporal_alignment semantics, and the fees caveat. Edge cases like null temporal alignment and unclassified legs are explicitly defined. Nothing needed for invoking or interpreting this tool 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?

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the interaction between topic and explicit-mode params, noting that explicit ticker/slug override the mapped side and that both modes share the same matcher. It also indirectly clarifies that custom pairings use both explicit fields together.

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 identifies the tool's deliverable precisely: a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is more specific than the generic Polymarket siblings. It is clear enough for an agent to pick it, but it never names or contrasts a sibling such as polymarket_arbitrage, so it stops short of explicit differentiation.

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 lays out two explicit modes ('topic' shortcuts vs explicit ticker/slug pairings) and states that both run the same matcher, giving an agent clear conditions for each. It also cautions that pre-mapped topics often return compatibility warnings and that pre-mapped ≠ tradeable, which is useful decision context. It does not explicitly say when to prefer this over sibling tools like polymarket_arbitrage, but internally the usage guidance is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds scoping details (anonymous IP, BYO key hash, account ID) and the listing behavior when key is omitted, complementing the 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?

Two sentences that are front-loaded with the primary action, followed by usage guidance and scoping. No unnecessary words.

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

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

The description covers purpose, usage, behavior, and scoping. Without an output schema, it implies return of a value or list of keys. Minor gap: does not explicitly mention behavior for missing keys, but overall complete.

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

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

Schema coverage is 100% with a clear description for the single optional parameter. The description reinforces that omitting the key lists all keys, adding no new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb (retrieve/list) and the resource (saved values/keys), distinguishes from sibling tools (remember, forget), and specifies the scoping mechanism.

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 (look up stored context) and pairs it with remember and forget. It does not explicitly list when not to use it, 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?

Beyond annotations (readOnly, idempotent, not destructive), the description reveals that mark_read:true modifies read state so future calls exclude returned events, and that response includes specific fields. This adds valuable behavioral context not captured by annotations alone.

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 (3 sentences), front-loaded with the primary action, and each sentence adds distinct value. No redundant or wasteful 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 the tool has 5 optional parameters, no output schema, and rich annotations, the description covers the core functionality, return fields, filtering, state mutation, and an alternative access method. It omits details on unread_only and error cases, but these are minor for a read-oriented tool.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description reinforces the meaning of type, since, and mark_read, but does not add significant new semantics beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states that the tool pulls fired events from a subscription feed, returning most recent alerts with source, citation_uri, and raw event payload. This is a specific verb+resource action, and it distinguishes from siblings like list_subscriptions by focusing on alerts rather than 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?

The description provides usage tips like filtering by type and since, using mark_read for state management, and mentions that polling works and the same feed is available via a GET endpoint. However, it does not explicitly compare to sibling tools or state when to use this tool versus alternatives, so guidance on selection is limited.

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

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

Annotations already mark the tool as readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds critical behavioral context: fan-out to SEC EDGAR, GDELT→GNews fallback with rate-limit handling, USPTO soft-fail due to API sunset, and date parsing (ISO vs relative). None of this is in the annotations, adding significant value.

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 dense but effective, using examples to illustrate intent and concisely summarizing behavior. It could be slightly more structured (e.g., separate source behaviors), but every sentence adds value without redundancy.

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

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

Given no output schema, the description still specifies the return format (structured changes by source, total_changes, citation URIs). It covers all parameters, data source behaviors, and use-cases. For a multi-source tool with fallbacks, this is complete and actionable.

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 that 'type' only supports 'company', providing examples for 'since' (ISO and relative) and a recommended default '30d', and explaining 'value' as ticker or zero-padded CIK. This improves usability beyond the schema.

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

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

Description starts with concrete example queries, identifies the tool as a change feed for a company within a time window, lists three data sources, and explicitly distinguishes from the sibling 'entity_profile' tool in the last sentence. This clearly states what the tool does and differentiates 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?

Provides when-to-use context through example queries and mentions the alternative 'entity_profile'. However, it does not explicitly state when not to use this tool or compare with other siblings like 'ask_pipeworx' or 'deep_research'. Still, the guidance is clear enough for typical use cases.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds value by explaining the key-value scoping, session persistence (24h for anonymous), and that it is a write operation (readOnlyHint=false) without contradicting 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 at four sentences, front-loaded with the main purpose, and every sentence adds value. No redundancy or 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 two string parameters and no output schema, the description covers purpose, usage guidance, behavioral context, and pairing with siblings. It is completely 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 coverage is 100% with descriptions for both parameters. The description reinforces the schema with examples (e.g., 'subject_property') but does not add significant new semantic meaning beyond the schema.

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

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

The description clearly specifies the verb 'Save', the resource 'data', and the context 'reuse later across sessions'. It explicitly distinguishes from sibling tools by mentioning 'recall' and 'forget' for retrieval and deletion.

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 states when to use: 'when you discover something worth carrying forward'. It also provides scoping and persistence details (authenticated vs anonymous). However, it does not explicitly exclude use cases or mention when not to use.

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

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

The annotations already signal read-only, idempotent, and non-destructive behavior, and the description adds substantial behavioral context: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF or OpenFIGI is unavailable, and concrete output identifiers per entity type. This goes well beyond the structured annotation hints.

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 and information-rich, and it front-loads the core purpose before diving into supported types. However, the company-type section is a long, nested, parenthetical-heavy block that could be more scannable. It is not wasteful, but its structure is more baroque than ideally concise.

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

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

Given the tool's complexity and the absence of an output schema, the description covers a great deal: input forms, supported types, returned identifiers, source systems, and failure degradation. It does not explicitly describe the no-match case or the exact response shape, which would make it fully complete, but it is sufficient for selecting and invoking the tool correctly.

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

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

The schema already documents both parameters thoroughly, including the value-format warning about not passing full noun phrases. The description adds extra meaning beyond the schema by introducing ISIN as an accepted company input, detailing entity-type-specific outputs, and clarifying how ownership and non-equity instruments resolve. This is useful enrichment on top of 100% 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 states a specific verb and resource: resolving user-spoken entity names to canonical/official identifiers, with explicit supported types and example queries. It clearly positions the tool as the first stop whenever an agent has a name but needs an ID, which also distinguishes it from the sibling tools like entity_profile and compare_entities.

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: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion-based 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 adds behavioral details beyond annotations: it reveals the tool probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. Annotations already indicate safe read-only operation; description complements this 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?

Two sentences, front-loaded with purpose. Every sentence adds value—no filler. Well-structured for quick agent 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?

Given no output schema, description adequately describes return type and fields (ranked list with score, confidence, signal density). Annotations cover safety. All relevant information is present for a tool of this complexity.

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

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

Schema coverage is 100%, but description adds value by clarifying that the first entity is treated as the 'subject' for narrative and that the output is a ranked list with score, confidence, and signal density per entity. This goes beyond what the parameter descriptions provide.

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

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

Description uses specific verb-resource combination: 'Compare AI visibility across multiple entities side-by-side'. Clearly distinguishes from siblings like ai_visibility_check (single probe) and compare_entities (likely different comparison type).

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 use case: 'Useful for competitive AI-marketing audits' and provides example question. Implicitly contrasts with ai_visibility_check by mentioning it probes each entity with that tool. Could benefit from explicit when-not-to-use or alternatives, but context is clear.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed lists timeouts. 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 detailed but front-loaded with key purpose and usage. Every sentence adds value, though slightly long. Could be slightly tighter but well-structured.

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

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

Despite no output schema, the description details return fields (summary block, advisories, links, alternatives) and error behavior (partial failures, sources_failed). Complete for the tool's complexity.

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

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

Both parameters are described in schema (100% coverage). Description adds: scoped packages accepted, version defaults to latest, and context that checking a new version may trigger first-time measurement delay.

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

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

The description clearly states it performs a composite check for npm packages, combining deps.dev and bundlephobia, and answers questions like 'is X safe/popular/small'. It distinguishes from siblings by being npm-specific and composite.

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

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

Explicitly says when to use: when an agent asks about safety, popularity, size, or cost. Also notes ecosystem limitation (NPM only) and points to alternative for other ecosystems (deps.dev:version directly). 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?

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. No contradictions with annotations.

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

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

The description is concise: two sentences front-load the purpose, then technical details and usage guidance are added without fluff. Every sentence contributes useful 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 parameter count, full schema coverage, and no output schema, the description is complete. It explains the search mechanism, character limit, and how to pair with a sibling tool, leaving no gaps for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing the max character length for text and example queries, enhancing understanding beyond the schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with concrete examples (SEC 10-K, article, tool result) and specifies the output (passages with offsets and scores). It distinguishes from siblings like ask_pipeworx_grounded.

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 when to use: 'when the record is too big to cram into the prompt'. Describes benefits (saves context, returns only relevant passages) and relates to the sibling tool ask_pipeworx_grounded for a complete workflow.

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

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

The description extensively discloses behavioral traits: it returns a new subscription id, requires authentication, details type-specific parameters and delivery channels with constraints (e.g., SMS cap, webhook auto-disable, signing). This adds significant value beyond annotations, which indicate non-read-only, non-destructive, idempotent, and open-world behavior. 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?

The description is well-structured, starting with the main purpose then detailing types and delivery. While comprehensive, it is slightly long; however, every sentence adds value given the complexity. It effectively front-loads key information.

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

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

The description covers all necessary aspects: tool function, authentication requirements, supported types with exact parameters, all delivery channels with limitations, and the return value (subscription ID). No output schema exists, but the description adequately explains the response. The sibling tools are diverse, but the description is self-contained and complete for its complexity.

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

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

The description adds substantial meaning to all parameters. It provides concrete examples for each subscription type, explains the format for 'params', and details the 'delivery' object including validation rules (e.g., phone verification, webhook signing). This enriches the schema, which already has 100% coverage, with actionable guidance.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the subscription ID. It specifies supported types and delivery channels, making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'unsubscribe', which would improve clarity.

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

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

The description provides context for when to use the tool: to create a subscription for live-data events. It mentions the requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. However, it lacks explicit guidance on when not to use this tool or alternatives (e.g., for managing existing subscriptions).

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

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

The description adds value beyond annotations by explaining the output (example questions with tool/argument shapes) and the context of use (onboarding). Annotations already indicate read-only, open-world, idempotent, non-destructive, so the description complements them well without contradiction.

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

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

The description is informative but somewhat verbose, containing multiple examples and details that could be streamlined. It is front-loaded with example questions but could be more concise.

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

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

Given no output schema, the description adequately explains the return value (category-bucketed example questions with tool shapes). It covers the single parameter, use cases, and provides clear instructions. It is complete for an onboarding tool.

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

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

The schema covers the parameter description (100% coverage), and the description adds meaning by explaining the effect of omitting vs. passing the 'topic' parameter, which is 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 is an onboarding entry point that returns category-bucketed example questions. It distinguishes from siblings by specifying its use case and mentioning it provides tool+argument shapes, but it does not explicitly name sibling tools for comparison.

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

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

The description provides explicit guidance on when to use this tool ('FIRST when you do not yet know what Pipeworx can do'), how to call it with or without the 'topic' parameter, and what it returns. It does not explicitly state when not to use it or mention alternatives, 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?

The description adds significant behavioral context beyond annotations: ownership enforcement and deactivation vs deletion. It explains what happens to the data (historical events remain available via recent_alerts), which is not covered by 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, no wasted words. The action is front-loaded, and constraints and effects are clearly stated in the second sentence.

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 a simple single-parameter input, the description covers all necessary aspects: what it does, ownership constraint, non-destructive effect, and where to find historical data. It is fully complete for agent invocation.

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

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

The schema has 100% coverage with a description for the 'id' parameter. The tool description does not add further meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool cancels a subscription by ID, using specific verb (cancel) and resource (subscription). It distinguishes from sibling tools like subscribe, list_subscriptions, and recent_alerts by specifying the action 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?

The description provides usage context: ownership enforcement (only cancel own subscriptions) and the effect (deactivation, not deletion). It implicitly suggests using recent_alerts for historical events, but does not explicitly name alternatives or exclusions.

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

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

Annotations already provide readOnly/idempotent hints, but the description adds rich behavioral detail: the dual pipeline (SEC EDGAR fast path vs grounded fallback), the precise meaning of each verdict, and a critical warning that could_not_verify means the check did not happen and must not be treated as evidence. This goes well beyond what annotations convey.

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

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

Though long, every sentence earns its place: it includes invocation examples, pipeline routing, verdict definitions, caller instructions, and a clear 'IMPORTANT for callers' note. The structure is logical and front-loaded with the core purpose, making the length justified.

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

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

For a tool with no output schema, the description is remarkably complete. It explains inputs, internal processing paths, return values, edge cases (could_not_verify vs unsupported), and even advises on how to interpret each verdict. There are no significant gaps for an agent to invoke and use it correctly.

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

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

Schema coverage is 100% (both parameters have descriptions), but the description adds extra practical guidance on tolerance_pct—e.g., setting 1-2 for hallucination detection and explaining the default behavior—plus illustrative claim examples. This adds value beyond the schema, though the schema already does most of the heavy lifting.

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

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

The description clearly states the tool's purpose with a specific verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by focusing on fact-checking claims and explicitly mentions replacing 4-6 sequential calls, making its role unique among the listed tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides clear routing context for company-financial vs other claims. It does not name alternative tools or state when not to use it, but the context is strong enough for a 4.

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