Washington DMV (Dept of Licensing)

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds concrete behavioral details: default model (Llama-3.3-70b, free), optional Anthropic probing with BYO key, and return fields (score, confidence, signals, raw_response). All consistent with annotations.

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

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

Three sentences: first states core function, second explains model options and key usage, third lists use cases and output. Each sentence earns its place; no wasted words.

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

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

Despite no output schema, the description explicitly lists return fields (score, confidence, signals, raw_response, combined view). Combined with thorough annotations (readOnly, idempotent, etc.), the description is complete for an audit tool.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description reinforces these (e.g., 'entity' is the thing to ask about, '_apiKey' needed for Anthropic) but does not add new semantics beyond what's in the schema. Baseline 3.

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

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

The description clearly states the tool probes LLMs for brand/business visibility and scores it per model. It specifies the verb 'probe' and the resource 'LLMs for visibility', and distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on per-model scoring and return structure.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' This gives clear context but does not exclude other tools or say when not to use it.

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

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

Annotations already good, but description adds valuable context: routes to 5,305 tools across 1,391 sources, fills arguments, returns structured answer with pipeworx:// citation URIs. 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?

Long but well-structured, front-loaded with key instruction, includes examples and alternatives. Could be slightly more concise but every sentence adds value.

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

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

Comprehensive for a tool that accepts natural language questions and returns structured answers with citations; missing output schema is mitigated by description of returned format. Adequate given complexity.

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

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

Schema coverage is 100% with aliases and examples; description does not add extra parameter detail beyond what schema provides, so baseline 3 is appropriate.

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

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

Description clearly states the tool answers factual questions with authoritative structured data, distinguishes from siblings by advising to start here and step up to grounded or deep_research for specific needs.

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

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

Explicitly tells when to prefer over web search, when not to use (step up for grounded or deep_research), and provides concrete examples of question types.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false, which the description does not contradict. The description adds operational context: that it's a beta with candidate improvements, currently identical to the stable version, and that it is a full working router. This complements the annotations well.

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

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

The description is a single paragraph of about five sentences. It is front-loaded with the key identity (beta version of ask_pipeworx) and provides necessary details without excessive verbosity. Could be slightly more concise, but overall 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?

Given the complexity of a universal router with many underlying tools and no output schema, the description adequately covers the tool's purpose, relationship to the stable version, current state, and usage guidance. It enables an AI agent to understand when to use this beta version.

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

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

The input schema has 6 parameters but they are all aliases for 'question', with 100% schema coverage. The description does not add further meaning beyond stating 'same arguments as ask_pipeworx'. Since schema coverage is high, the baseline of 3 is appropriate; no additional value from the 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 identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,305 tools, arguments, and response shape. It distinguishes itself from the stable version by mentioning candidate routing improvements, making the purpose and differentiation explicit.

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

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

The description states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It implies when to use (experimental routing) and describes the current state (no active candidate, so identical to stable). It does not explicitly list when not to use, but the context is clear.

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

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

Annotations already indicate safety (readOnly, idempotent, not destructive). Description adds crucial behavioral details: refusal reasons, evidence extraction, extra LLM call cost, and that it only uses tool result content. 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?

Front-loaded with key phrase, logically structured, but slightly longer than minimal. Every sentence adds value, though could be trimmed marginally.

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

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

Given no output schema, description fully explains return format, refusal reasons, and tool behavior. Covers all essential aspects for correct invocation and interpretation.

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 clear alias descriptions. Description adds little to parameter semantics beyond restating that the tool fills arguments. Baselines at 3 given high schema coverage.

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

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

Description explicitly states it is a 'hallucination-resistant answer mode for high-stakes reads' and contrasts with sibling ask_pipeworx for casual lookups. Clearly communicates the purpose: to provide grounded, evidence-based answers.

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?

Specifies when to use: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' Provides explicit alternatives and contextual cues.

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

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

The description goes far beyond annotations (readOnlyHint, etc.) by detailing fan-out behavior, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms (low-confidence short-circuit, closed market handling), and resolution rule risk. 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 long but well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded with the core purpose. While verbose, every sentence adds value for a complex tool.

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

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

Despite no output schema, the description covers all critical aspects: response fields, error conditions, resolution risk, and edge cases (low confidence, closed markets, wide spreads). It is comprehensive for the tool's complexity.

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

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

Schema coverage is 100% (all 3 parameters documented). The description adds substantial meaning: explains the market parameter's three possible formats, the depth enum (quick vs thorough with defaults), and include_raw's effect (summary vs full payload). The input schema examples further clarify usage.

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

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

The description clearly specifies the tool's action: researching a Polymarket bet by pulling Pipeworx data. It states input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from sibling tools like deep_research or ask_pipeworx by being specific to Polymarket bets.

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 usage scenarios (e.g., 'should I bet on X') and examples of fan-out for different bet categories (crypto, Fed, sports). It does not directly compare to sibling tools like polymarket_arbitrage or polymarket_edges, but the context is clear enough for an agent to infer when to use this tool.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: uses SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, FAERS for drugs, results sorted by primary metric, returns paired data with citation URIs. No contradiction with annotations.

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

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

Description is a single paragraph but front-loaded with specific query examples. Every sentence serves a purpose: examples, use preference, data source details, sorting behavior, and return format. No wasted words.

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

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

For a tool with 2 parameters, no output schema, and simple structure, the description is thorough. It explains data sources, parameter constraints, sorting, and response format (paired data + URIs). No gaps remain 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%, but description adds significant meaning beyond schema: type enum values are explained with examples (company: financials from 10-K; drug: FAERS counts, FDA approvals, trials). Values parameter specifies acceptable formats (tickers/CIKs for company, drug names for drug) and count constraints. This heavily augments the schema's minimal descriptions.

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

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

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides example queries ('Compare X and Y', 'which is bigger', 'rank these companies') that show the exact use case. Distinguishes from sibling tools like entity_profile by emphasizing parallel lookup over sequential single-pack 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Also details when to use each entity type (company vs drug) with specific data sources and constraints (max 5 items, min 2). No ambiguity about when this tool should be used.

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, non-destructive. Description adds extensive behavioral context: account requirement, paid plan for thorough, time expectations (15-90s), gap recovery, contradictions, citation format with hop field, semantic excerpting, and the fact that large records are not head-truncated. No contradiction with annotations.

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

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

Description is quite long but densely packed with valuable information. Front-loaded with critical account requirement and fallback. Each sentence adds unique value, but could be slightly more streamlined (e.g., separate account/pricing info). Still, highly informative.

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 only 2 params with no output schema, the description covers virtually everything needed: use cases, limitations, behavior, expectations, comparisons, and technical details. Missing only minor things like error handling or rate limits, which are not critical.

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

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

Schema has 100% coverage with descriptions for both parameters (depth enum, question). Description adds extra context: e.g., depth values' specific behaviors (quick=3 facets, standard=5 + gap recovery, thorough=8 + iterative hop), and that question should be natural language and broad. While schema covers basics, description enriches understanding.

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

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

The description clearly states it is a grounded multi-source research tool across 1,391 structured data sources, decomposing questions into facets and routing to 5,305 tools in parallel. It distinguishes itself from siblings like ask_pipeworx, which is for single lookups or current news.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not (breaking news, single lookup). Provides specific alternatives: ask_pipeworx for single lookups and current news, with reasoning.

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 read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output format and efficiency, 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 somewhat lengthy but well-structured: it starts with the core purpose, lists examples, then explains the return format. Every sentence adds value. However, the list of data domains could be slightly shortened without losing clarity. Overall, it earns its length.

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

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

Given the tool's complexity (discovery across many domains) and the absence of an output schema, the description adequately explains what the tool returns (tool names, descriptions, full schemas with examples). Parameter documentation is complete, and usage guidance is provided. No gaps are evident.

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 extra value by providing examples of valid queries ('look up FDA drug approvals', 'analyze housing market trends') and explaining that the 'limit' parameter controls the top-N results. This enhances understanding beyond the schema's property descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific use cases (SEC filings, FDA drugs, etc.), which distinguishes it from sibling tools that are domain-specific. The verb 'discover' combined with 'top-N most relevant tools' makes the action unambiguous.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use the tool, implying alternatives (other specific tools) when the user already knows what they need.

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

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

Annotations already mark it as read-only and idempotent; description adds important behavior such as USPTO patent data soft-fail 'until reactivated', GDELT→GNews fallback, and specific fields returned. 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 long but each sentence adds value. It front-loads the purpose and usage. Minor redundancy in examples but overall effective. Could be slightly more concise without losing substance.

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 covers inputs, outputs, and limitations well. Could mention error handling or response format more explicitly, but it's quite comprehensive for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description echoes schema info (ticker or CIK, names not supported) but doesn't add significant new semantics beyond what the input schema provides.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides examples and lists specific outputs (CIK, filings, fundamentals, patents, news, LEI), distinguishing it from siblings like resolve_entity 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?

Explicitly says 'ALWAYS PREFER over chaining single-pack... lookups when the user asks for a holistic view' and advises to use resolve_entity if only a name is provided. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations provide destructiveHint=true and idempotentHint=true, which already indicate mutation and safety. The description reinforces the deletion action and adds context about clearing sensitive data, but does not disclose additional behavioral traits such as whether deletion is permanent or what happens on non-existent keys.

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 with two focused sentences. It front-loads the purpose and includes usage context without unnecessary words.

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

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

Given the simple structure (one parameter, no output schema), the description is fairly complete. It explains the purpose, usage scenarios, and relationships with siblings. It could mention more about the behavior for missing keys, but overall it's 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?

The input schema has 100% coverage with a description for the 'key' parameter. The tool description does not add extra meaning beyond what the schema already provides, so it meets the baseline.

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

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

The description states 'Delete a previously stored memory by key', which is a specific verb and resource. It clearly distinguishes from siblings like 'remember' and 'recall' by focusing on 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?

The description explicitly lists three scenarios for use: when context is stale, task is done, or clearing sensitive data. It also pairs with sibling tools, providing clear usage context. However, it does not explicitly state when not to use this tool.

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

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

Annotations declare readOnlyHint, idempotentHint, and no destructiveness. The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting standard markdown. This provides context 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?

Three sentences are front-loaded with purpose, then method, then use cases. Every sentence adds value; no redundancy or fluff. Highly efficient.

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

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

Given the simple tool (2 params, no output schema, clear annotations), the description covers what it does, how it works, and when to use it. No gaps in context for an AI agent.

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

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

Schema coverage is 100% with both parameters (url, max_links) described. The description mentions fetching the page and extracting links but does not add substantial meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the action (generate), the resource (llms.txt file), and the target audience (AI crawlers). It distinguishes from sibling tools like ai_visibility_check or scan_competitor_ai_presence by specifying the exact output format and use case.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing a competitor. While it doesn't state when not to use, the positive guidance is strong and sufficient for typical scenarios.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return field details and explains default behavior (active only) and optional param for inactive. No contradictions.

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

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

Two-sentence structure is efficient: first sentence states purpose and output, second sentence gives usage guidance. No wasted words.

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

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

Given the tool's simplicity (one optional param, no output schema), description covers purpose, usage, return data, and parameter effect. Fully adequate.

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

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

Schema coverage is 100% with description for the single parameter. Description adds context by mentioning 'active subscriptions' versus including inactive, tying the parameter to behavior.

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

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

Description clearly states 'List the caller's active subscriptions' with verb and resource, and lists return fields. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly provides usage scenarios: 'review what you're monitoring before adding more or to find an id to cancel'. Lacks explicit alternatives but context is clear.

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

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

Annotations are mostly false (readOnlyHint, destructiveHint, etc.), so the description carries the burden. It discloses rate limiting, that feedback is free, and that the team reads digests daily and uses feedback to shape the roadmap. It does not detail any side effects (e.g., if feedback is immediately visible), but overall adds sufficient behavioral context.

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

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

The description is concise yet comprehensive. Every sentence serves a purpose: purpose statement, usage scenarios, content guidelines, team process, rate limits, and cost. It is well-structured and front-loaded with the core action.

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 feedback tool with three parameters (two required) and no output schema, the description fully covers what the agent needs to know: when to use, what to include, constraints, and behavioral aspects. 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 parameters are already documented. The description adds meaningful guidance: instructs users to describe issues in terms of Pipeworx tools/packs and not paste end-user prompts. It also reinforces the enum meanings for the 'type' parameter, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific scenarios (bug, feature/data_gap, praise) and distinguishes itself from sibling tools, which are query/research tools, by being the only feedback channel.

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

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

The description provides explicit when-to-use guidance: for broken tools (bug), missing tools (feature/data_gap), or praise. It also tells what not to do ('don't paste the end-user's prompt') and notes rate limits (5 per identifier per day) and quota ('Free; doesn't count against your tool-call quota').

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 valuable behavioral details: caching (5min-1h depending on window), data source (CF analytics-engine), and privacy (no PII, just counts). This goes well 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 well-structured: first sentence states core functionality, followed by use cases and data source notes. Each sentence is concise and informative, no fluff.

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

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

For a read-only, idempotent tool with one optional parameter, the description fully explains what is returned (top tools, top packs, total call volume) and how the data is derived. No gaps given 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% with enum and description for 'window'. The description adds context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enriches the schema's 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 tool returns top tools, top packs, and total call volume over a configurable window. It uses specific verbs ('Returns') and resource ('top tools, top packs, and total call volume'), distinguishing it from siblings like 'discover_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 three explicit use cases: discovering hot data sources, confirming popular tools, and aligning use case with agent needs. It implicitly contrasts with other tools by focusing on trending signals.

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, openWorldHint=true, and destructiveHint=false. The description adds extensive context: top-200 market scan, event mode specifics (date-axis/threshold-axis ordering, partition check with 3pp threshold), topic mode (Jaccard similarity ≥0.30, placeholder filter, fill check with realizable vs theoretical edge). This exceeds annotation info significantly.

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

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

The description is fairly long but well-structured: starts with a summary, then breaks down each mode with clear headings (implied by capitalization) and details. While slightly verbose, every sentence adds value given the tool's complexity. Front-loads the core purpose effectively.

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

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

Despite no output schema, the description details the response structure: 'opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and event-mode partition_check fields. It also covers fill-check behavior and when not to trade, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for both `event` and `topic`. The description adds meaning by explaining how each parameter changes behavior, providing example slugs and seed questions, and describing the context (e.g., 'walks child markets', 'searches related events').

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

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

The description starts with a clear verb+resource statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) with specific examples, differentiating it from siblings like `polymarket_edges` and `polymarket_fill_risk`.

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 each mode: 'Call with NO args for a trending_scan... pass `event` for... partition_check, or `topic` for cross-event scan.' It explains the benefit of cross-event mode ('catches patterns that single-event misses'). While it doesn't explicitly state when not to use, the guidance is clear enough.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context: three model families, edge calculation details, caching policy (1h KV-level), diagnostics output, and tradeable-edge knobs. No contradictions with annotations.

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

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

The description is well-structured with clear sections and enumeration, but is quite verbose. It includes necessary details but could be more concise. Front-loads purpose, then dives into models and filters.

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 is remarkably complete. It explains internal models, response structure (by_segment, fed_candidates, diagnostics), edge calculations, and caching. Compensates fully for missing output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add parameter details beyond what the schema already provides; it mentions some parameters in context but without new semantic value.

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

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

The description clearly states the tool scans Polymarket markets to return opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It uses strong verbs and distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx data disagreement.

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

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

The description provides clear context for when to use the tool (discovering daily betting opportunities without paging markets) but does not explicitly mention when not to use it or name alternative tools. The guidance is implicit and sufficient for most cases, but lacks explicit exclusions.

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

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

The description provides extensive behavioral details: it uses daily snapshots, generates trend and decay metrics, explains limits such as 60-day TTL, and clarifies that decay numbers come from daily closes. These go beyond the annotations, which already indicate read-only and idempotent behavior. No contradiction with annotations.

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

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

The description is comprehensive yet well-structured. It begins with the core purpose, then explains parameters, then details the response format, and ends with limitations. No sentences are wasted; each adds necessary context.

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 absence of an output schema, the description fully compensates by detailing the response structure (tracked, expired, snapshot_dates) and explaining each field. It also covers limitations and interpretation nuances. The description is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the description's contribution is limited. It restates default and max values, but also provides context that days is the lookback and window is the snapshot family. There is a minor mismatch: description says max 30, schema says clamp 2-30. Overall, the description adds some semantic context but does not significantly surpass the schema.

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

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

The description explicitly states the tool provides edge persistence and decay telemetry, answering how long an edge has existed and its decay trend. It distinguishes from the sibling tool 'polymarket_edges' by focusing on time-series analysis rather than snapshot data.

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

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

The description frames the tool's purpose around a specific question: how long an edge has existed and if it's shrinking. This guides when to use it. However, it does not explicitly mention when not to use or compare with alternatives, though the sibling name 'polymarket_edges' suggests that tool provides raw edges.

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

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

Annotations already indicate safety (readOnlyHint, idempotentHint). The description adds significant behavioral details: how it 'walks the ladder,' returns verdicts like 'clean|degraded|cannot_fill,' and warns about forced_directional_risk. No contradictions with annotations.

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

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

The description is well-structured with bold headers and bullet points, front-loading key information. It is dense but not overly verbose; however, it could be slightly shortened by merging some repetitive phrases while retaining clarity.

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

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

Given the complexity (two modes, multiple return fields) and lack of output schema, the description thoroughly explains the return values, verdict categories, and edge cases (thin_legs, forced_directional_risk). It is complete enough for an agent to understand the tool's behavior and output.

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 4 parameters. The description greatly enhances understanding by explaining the semantics in context, such as the dual meaning of size_usd ('max spend on buys, target proceeds on sells') and the default side logic for basket mode.

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 defines the tool as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and the purpose is precisely stated with specific verbs and resources.

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 instructs to 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It provides clear context on when to use, why it matters, and the risks of not using it, effectively guiding the agent.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description extensively details behavioral traits: the two modes, response structure with safety fields (compatibility_warning, temporal_alignment), and edge cases like skipped cross-type comparisons. This goes far beyond what annotations provide.

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

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

The description is well-organized into clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. However, it is somewhat verbose with repeated warnings (e.g., 'pre-mapped ≠ tradeable' appears twice), and could be slightly more concise.

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

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

Given the tool's complexity (cross-venue, multiple modes, safety checks) and the absence of an output schema, the description thoroughly explains the response structure, including leg-by-leg prices, top_spreads_pp, compatibility_warning conditions, and temporal_alignment. No gaps are apparent.

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

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

With 100% schema coverage, the description adds significant value by listing all 10 topic shortcuts, explaining explicit overrides, and providing usage examples. It clarifies the relationship between parameters (e.g., topic auto-fetches events, explicit tickers override).

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies two distinct modes (topic shortcuts and explicit tickers) and differentiates itself from sibling tools like polymarket_arbitrage by focusing on cross-venue 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 context on when to use the tool, such as when venues price outcomes up to 25pp apart, and includes cautionary notes like 'pre-mapped ≠ tradeable.' However, it does not explicitly compare against sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds scoping detail (based on identifier) and confirms idempotent 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 four sentences, each serving a purpose. It front-loads the main action and adds usage context efficiently with no redundant text.

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

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

With one optional parameter, no output schema, and complete annotations, the description fully covers purpose, scoping, and sibling relationships. 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% and already documents the key parameter with the note to omit for listing. The description repeats this info without adding new meaning beyond the schema.

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

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

The description clearly states the tool retrieves values saved via remember or lists all keys. It specifies the verb (retrieve/list) and resource (saved context), and distinguishes from siblings like remember and forget.

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

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

The description explains when to use (look up stored context) and provides alternatives (re-deriving from scratch). It mentions pairing with remember/forget but does not explicitly state exclusion 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?

The description discloses a side effect: setting mark_read:true flags events as read, modifying state. However, the annotations include readOnlyHint: true, which indicates no state changes, creating a contradiction. According to the rubric, a contradiction requires a score of 1.

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

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

The description is concise (four sentences) with no redundancy. It front-loads the main purpose and organizes details logically: what is returned, how to filter, side effect, and alternative access.

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 (5 optional parameters, no output schema, rich annotations), the description is complete. It explains return fields, filtering options, a side effect, and alternative access, leaving no significant gaps for an agent to use the tool correctly.

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

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

The schema covers 100% of parameters (baseline 3), and the description adds meaningful context: examples for type filter ('sec_8k'), explanation of since as ISO timestamp, and the effect of mark_read. This provides extra value beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts. It specifies the resource (subscription feed) and the action (pull/return), and distinguishes from sibling tools like recent_changes by focusing on alerts.

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

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

The description provides clear usage context: filtering by type and ISO timestamp, using mark_read to manage read state, and mentioning that polling works. It also offers an alternative URL for scripts. However, it does not explicitly contrast with siblings or state when not to use this tool.

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

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

Annotations declare readOnlyHint and no destructiveness. The description adds behavioral details: fans out to multiple sources, soft-fails for patents, accepts relative dates, and returns structured changes with citation URIs. 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 comprehensive but somewhat long. It is well-structured with examples, conditionals, and clear grouping. A minor reduction in length could improve conciseness without losing value.

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

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

Given no output schema, the description details the return structure: changes[] grouped by source, total_changes, and citation URIs. It covers all aspects needed to use the tool effectively, given the three parameters and multiple data sources.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains type is only 'company', provides typical usage for since ('30d' or '1m'), and clarifies value accepts ticker or CIK. This goes beyond the schema.

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

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

The description explicitly states the tool provides a change feed for a company across SEC, news, and patents in one parallel call. It distinguishes from the sibling tool entity_profile by specifying that entity_profile is for static profiles.

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

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

The description provides explicit usage guidance with examples like 'What's new with X' and clearly states when not to use it: 'Use entity_profile instead when you want the static profile'. This effectively differentiates from 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?

Discloses scoping by identifier, persistence differences (authenticated vs anonymous), and retention duration. Annotations idempotentHint=true is not contradicted, and description adds behavioral context beyond annotations.

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

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

Four sentences with no wasted words. Front-loaded with purpose, then usage, then details. 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?

For a simple key-value storage tool with 2 parameters and no output schema, the description fully covers storage mechanism, retention, and pairing with siblings. 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 descriptions are already detailed (100% coverage). The description adds practical examples for key and value, enhancing understanding beyond schema.

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

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

Clearly states the tool saves data for reuse across conversations/sessions with a specific verb ('Save') and resource ('data'). Distinguishes from siblings by mentioning pairing with 'recall' and 'forget'.

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

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

Gives explicit context for when to use ('discover something worth carrying forward') and provides examples. Implicitly contrasts with recall/forget, but does not explicitly state 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?

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that calls cascade through multiple endpoints, auto-disambiguate, and return citation URIs, providing rich behavioral context beyond annotations.

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

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

The description is concise yet comprehensive, starting with user-facing examples, then stating purpose, usage order, and supported types with details. Every sentence adds value.

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

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

Despite no output schema, the description fully explains what is returned for each entity type, including identifiers and citation URIs. It covers the tool's role and internal process, leaving no gaps.

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

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

With 100% schema coverage, the description enhances parameter meaning by giving concrete examples (e.g., 'ticker (AAPL)') and explaining return values for each type (ticker, CIK, RxCUI, citation URIs).

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 resolves a name to a canonical identifier, with specific examples ('ticker for...', 'CIK for...') and lists supported entity types. It distinguishes from sibling tools by noting that other tools require the IDs returned by this 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It explains supported types and what each returns, but doesn't explicitly mention when not to use it or alternative tools.

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

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

Description adds value beyond annotations by explaining the probing process, ranking, and that the first entity is treated as subject. Annotations already indicate readOnlyHint, idempotentHint, etc., and description does not contradict them.

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

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

Three sentences with no wasted words: first states action, second explains process, third provides use case. Front-loaded and efficient.

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

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

Without output schema, description adequately explains output (ranked list with score, confidence, signal density). It covers input, process, and output. Could mention error handling or idempotency, but overall sufficient.

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

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

Schema covers all parameters (100% coverage), but description adds meaning: entities are probed with ai_visibility_check, first entry is subject for narrative, context is shared across probes. This enriches understanding beyond schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and returns a ranked list with metrics. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities by specifying the competitive audit use case.

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 says 'Useful for competitive AI-marketing audits' and gives an example question, implying when to use it. It does not explicitly state when not to use or name alternatives, but the context of sibling tools makes the purpose clear.

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

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

Annotations already mark the tool as read-only and idempotent. The description goes beyond by detailing the composite nature, external service calls, potential latency (5-30s for first measurement), graceful degradation, and the sources_failed field. 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 that front-loads the main purpose. Every sentence adds value, covering purpose, usage, limitations, return structure, and failure behavior. Slightly long but well-organized for the complexity.

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

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

With no output schema, the description thoroughly covers return values: summary fields, advisory details, links, and alternatives. It also explains failure modes and ecosystem limitations. Highly complete for a composite tool with external dependencies.

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

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

Schema description coverage is 100% for both parameters. The description adds minimal new information (scoped packages, default to latest version), which is already in the schema descriptions. 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 is a composite check for npm packages, integrating deps.dev and bundlephobia. It specifies the exact purpose: evaluating safety, popularity, and size. This distinguishes it from siblings like validate_claim or ask_pipeworx, which are unrelated.

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 an agent asks "is X safe / popular / small"' and notes the NPM-only limitation, suggesting alternatives for other ecosystems. It lacks an explicit 'when not to use' but provides enough context for appropriate usage.

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

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

Discloses technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Two dense paragraphs: first covers purpose and usage, second covers implementation details. 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?

Given 3 parameters, no output schema, and rich annotations, the description fully covers what the tool does, when to use it, how it works internally, and what it returns. Complete for an AI 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 has 100% description coverage, so baseline is 3. Description adds value by providing example queries for the 'query' parameter and clarifying the output format (passages with offsets and scores). This goes beyond schema.

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

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

Description clearly states it's semantic search inside a fetched record. Uses specific verb 'Search Within' and resource 'a Source'. Distinguishes from siblings by emphasizing it works on already-fetched content, and explicitly pairs with 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 states when to use: 'Use when the record is too big to cram into the prompt'. Provides alternative pairing with ask_pipeworx_grounded, guiding the agent on complementary tool usage.

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

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

Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds context: requires OAuth, returns subscription ID, details on type-specific parameters, delivery behavior (feed always on, optional email/SMS/webhook), rate limits (10 SMS/day), and webhook signing. No contradictions.

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

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

The description is front-loaded with the main purpose, then progresses logically: prerequisites, types, delivery channels. Despite length, every sentence adds unique value and there is no redundancy. It is well-structured for an agent to parse quickly.

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

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

For a tool with 3 parameters, nested objects, enums, multiple subscription types, and optional delivery channels, the description covers all essential aspects: prerequisites, type-specific parameters, delivery options, constraints (rate limits, verification, webhook details), and return value. 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 parameter descriptions, but the tool description adds substantial value: concrete examples for each subscription type's params (e.g., sec_8k: {ticker:'AAPL', items?}), explains delivery constraints (phone verification, webhook signing secret), and clarifies requirements (sponsor or condition for clinical_trial). This goes well 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 creates a subscription to a live-data event stream and returns an ID. It specifies the action 'create', the resource 'proactive monitoring subscription', and distinguishes it from siblings like 'unsubscribe' and 'list_subscriptions' by focusing on creation. The support for multiple types and delivery channels is explicitly listed.

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 prerequisites (Pipeworx OAuth account), lists supported subscription types with examples, and explains delivery channels including constraints (phone verification, SMS cap, webhook auto-disable). It mentions when to use (proactive monitoring) and references sibling 'recent_alerts' for pulling. No misleading 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 readOnly, openWorld, idempotent, non-destructive. The description adds context about returning live catalog examples and does not contradict annotations. It explains what the tool produces and its scope.

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

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

The description is well-structured with front-loaded purpose, alternative phrasings, and clear sections. It is somewhat lengthy but each sentence adds value. Minor redundancy in listing topics 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?

Despite no output schema, the description fully explains return content (category-bucketed examples with tool+argument shapes). It covers input, output, and usage context, making it complete for an agent to decide when and how to call.

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 single optional parameter. The description adds meaning by explaining the effect of omitting vs providing topic, and lists concrete example values, going beyond the schema's description.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs like 'returns' and positions itself distinctly from siblings by recommending first use.

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

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

Explicitly states when to use ('Use this FIRST when you do not yet know what Pipeworx can do'), how to use (with or without topic), and implies when not to use (after onboarding, move to meta-tools). Also mentions learning about meta-tools.

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

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

Beyond annotations (idempotentHint=true, destructiveHint=false), description reveals that the row is deactivated not deleted, preserving historical data. This adds key behavioral detail 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?

Three concise sentences, each providing distinct value: action, ownership enforcement, and deactivation behavior. No wasted words.

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

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

For a simple tool with one parameter, no output schema, and comprehensive annotations, the description fully covers behavior, constraints, and side effects. It even directs to an alternative for historical data.

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 'id' (uuid returned by subscribe). Description does not add additional semantic meaning beyond what the schema already provides, meeting baseline but not exceeding.

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?

Starts with a clear verb and resource: 'Cancel a subscription by id.' Distinguishes from sibling tools like 'subscribe' (creates) and 'list_subscriptions' (lists) by the action of cancellation.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding that it's for self-owned subscriptions. Also informs that historical events remain via 'recent_alerts', providing a when-not or alternative context, though no explicit comparison to 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, openWorldHint, idempotentHint, and destructiveHint. The description adds value by describing the two processing paths, the output format (verdict, actual value with citation, reasoning), and the efficiency of replacing multiple calls. There is 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 around 150 words, front-loaded with trigger phrases and clear structure (purpose, two paths, return values, efficiency). While every sentence adds value, it could be slightly more concise without losing essential details.

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

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

No output schema exists, but the description fully explains the output: verdict types, actual value with citation, and reasoning. It accounts for both claim types and parameter usage. With two well-described parameters and comprehensive behavioral details, the description leaves no obvious gaps for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with both parameters described. The description adds context: tolerance_pct overrides the implied tolerance, and it provides examples of natural-language claims. This complements schema information and clarifies parameter usage.

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

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

The description starts with clear trigger phrases like 'Is it true that...' and defines the tool's purpose as natural-language claim verification against authoritative sources. It specifies two separate processing paths (structured SEC EDGAR for company financials, grounded pipeline for other claims) which clearly distinguishes it from sibling tools.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two different processing paths for financial vs. other claims. However, it does not explicitly mention when NOT to use this tool or suggest alternative tools for different contexts, such as open-ended research.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds valuable context: one row per registered vehicle, fleet counts, breakdown dimensions, and that average/median range and CAFV eligibility are reported. 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 two paragraphs with front-loaded purpose. Every sentence adds value. It is concise but could be slightly more succinct by merging the example questions into the first paragraph. Still, it is well-structured without waste.

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

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

The tool has 10 parameters and no output schema. The description covers return values (counts, breakdowns, average range, CAFV eligibility) and provides specific query examples. It lacks information on sorting or null handling but is otherwise comprehensive for a read-only count tool.

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

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

Schema coverage is 100%, so baseline is 3. However, the description adds meaningful details beyond the schema: it explains that make/model are upper case and matched as substring, gives the limit default and max, and lists group_by options with examples. This helps the agent use parameters correctly.

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

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

The description explicitly states it counts electric vehicles registered in Washington State, with breakdowns by geography, make, model, etc. It distinguishes itself from the sibling tool 'wa_dmv_registration_transactions' by clarifying it is fleet counts, not sales. The verb 'count' and resource 'EV population' are specific.

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

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

The description provides clear example questions (e.g., 'how many Teslas are in King County') that signal appropriate use cases. It does not explicitly state when not to use it, but the context is sufficient given the tool's clear scope. It distinguishes from the similar sibling by noting it's fleet counts, not transaction-based.

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 behavior. The description adds critical context beyond annotations: it clarifies that transaction counts are events, not vehicle counts, and defines the breakdown dimensions. No contradictions with annotations.

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

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

Description is a single, well-structured paragraph that front-loads the purpose, provides concrete examples, and includes a critical clarification about transaction vs. vehicle counts. Every sentence serves a purpose; no redundant or irrelevant 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?

Despite having 8 parameters, no required ones, and no output schema, the description is highly complete. It covers purpose, usage scenarios, parameter dimensions, examples, and a key caveat. It also references a sibling tool for a related but distinct query, ensuring the agent can correctly select the tool.

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

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

Schema description coverage is 100%, with every parameter documented. The description adds high-level examples and mapping hints (e.g., 'gas' → Gasoline) but does not significantly extend what the schema already provides. A score of 3 reflects adequate parameter information without additional semantic depth.

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

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

Description clearly states the tool counts vehicle registration transactions, specifies the breakdown dimensions (county, fuel type, etc.), and explicitly distinguishes from the sibling wa_dmv_ev_population tool. It directly answers example questions, leaving no ambiguity about the tool's purpose.

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

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

Description provides explicit guidance on when to use (for transaction counts by various dimensions) and when not to use (for electric fleet size, directing to wa_dmv_ev_population). It includes example queries and notes that each transaction is an event, not a vehicle count, preventing misuse.

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