qrcode

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

Annotations already state readOnlyHint and idempotentHint. The description adds behavioral traits: the return format (per-model objects with score, confidence, etc.), the fact that default model is free, and that Anthropic requires a BYO API key with direct payment. This goes beyond basic 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 four sentences with no wasted words. It is front-loaded with the core action, then details on models, output, and use cases. Every sentence earns its place.

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

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

The description, combined with the rich input schema and annotations, provides a complete understanding. It explains the tool's function, parameters, output format, and intended use cases, compensating for the lack of an 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 adds value by clarifying the default model behavior, the need for _apiKey only when 'anthropic' is in models, and the purpose of context parameter, enhancing 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 the tool's purpose: probing LLMs about an entity and scoring visibility per model. It uses specific verbs and resources, and distinguishes itself from siblings like scan_competitor_ai_presence by being broader and returning per-model scores.

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

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

The description provides context for when to use the tool (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs. paid model usage. However, it does not explicitly state when not to use or name 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?

Annotations already declare readOnly, openWorld, idempotent. Description adds that it routes to 3,751 tools across 886 sources and returns structured answers with citation URIs, which is valuable behavioral context beyond the annotations.

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

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

The description is efficient, with the key instruction front-loaded. All sentences add value (preference, domain list, routing info, examples). Could be slightly trimmed but no 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 description covers purpose, usage guidance, and examples. It mentions the return format (structured answer with citations). Given no output schema, this provides adequate completeness. Could mention that results are returned as text or JSON, but it's 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 has 100% coverage with detailed descriptions for each parameter (all aliases for question). The description adds context on the type of questions to ask (factual, authoritative), giving examples. This augments 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 answers factual questions from authoritative data sources, explicitly distinguishing it from web search and listing supported domains like SEC filings, FDA data, etc. Sibling tools include search_within and web search alternatives, so it differentiates well.

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 'PREFER OVER WEB SEARCH' and provides specific scenarios (e.g., 'what is', 'look up', 'find') along with examples. It doesn't list exclusions but the preference is strong 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?

Describes the extraction logic, return structure (including refusal reasons), and the fact it uses only tool data. Annotations already provide read-only and idempotent hints; the description adds significant context beyond annotations without contradicting them.

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

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

Very concise; each sentence serves a purpose: purpose, mechanism, return format, usage guidance, and trade-off. No unnecessary words.

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

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

Given the tool's complexity (routing, extraction, refusal reasons), the description is comprehensive. It covers purpose, usage, behavior, return structure, and limitations, leaving no obvious 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 all 6 parameters documented as aliases for 'question.' The description adds no new parameter information beyond what the schema already 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?

Clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explicitly differentiates from 'ask_pipeworx' by noting the extra LLM call and use case. The verb 'extracts' and resource 'answer from tool result' are precise.

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

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

Explicitly says 'use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups,' offering both when-to-use and when-not-to-use guidance with a clear trade-off.

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, non-destructive, idempotent. The description adds extensive behavioral context: market resolution, classification, fan-out patterns, response shapes, resolver contract (matching confidence, alternatives), parent_event extractor, news fields with fallback handling, safety short-circuits, illiquid spread warnings, and resolution-rule risk. All align with annotations without contradiction.

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

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

The description is excessively long (several hundred words) and packed into a single paragraph without clear section breaks. While informative, it is not concise; the first sentence captures the purpose, but the rest is a dense dump of edge cases and examples that could be structured or appended as separate documentation. Many agents would struggle 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?

Given the tool's complexity (3 parameters, no output schema, multiple behavioral facets), the description is remarkably complete. It covers resolver confidence, parent events, news fallbacks, safety triggers, illiquid markets, and resolution-rule risks. Examples of fan-outs for different bet types (BTC, Fed, Hormuz, sports, etc.) are provided. This compensates fully for the lack of an 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 covers all 3 parameters (100% coverage) with clear descriptions. The main description adds deeper context: how 'market' input is resolved (slug, URL, text), how 'depth' affects the fan-out (quick vs thorough with examples), and how 'include_raw' controls response size (default summarized, true for raw payloads). This extra meaning helps agents choose parameter values effectively.

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 verb ('Research'), resource ('Polymarket bet'), and core action ('pull relevant Pipeworx data in one call'). It specifies multiple input types (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on per-bet data research rather than cross-market analysis.

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

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

Explicit usage scenarios are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also details when to use 'quick' vs 'thorough' depth. However, it does not explicitly state when NOT to use this tool or name alternatives, though sibling tools cover distinct use cases.

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

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

Beyond annotations (readOnlyHint, openWorldHint, etc.), the description reveals key behavioral traits: for company type, it pulls latest 10-K financials from SEC EDGAR/XBRL with correct handling of off-calendar fiscal years; for drug type, it pulls FAERS and FDA data. It also mentions default sorting by primary metric and including citation URIs.

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 slightly verbose. However, it is well-structured: starting with usage examples, followed by detailed behavior per type, and ending with return format. The key information is front-loaded.

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

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

Despite no output schema, the description clarifies return format ('paired data + pipeworx:// citation URIs per entity') and covers both entity types thoroughly. Given the tool's simplicity (2 parameters), the description is complete.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains that type='company' fetches specific financial metrics (revenue, net income, cash, debt) and type='drug' fetches adverse-event counts, approvals, and trial counts. This goes far beyond the enum values in the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 entities (companies or drugs). It provides explicit verb patterns ('Compare X and Y', 'X vs Y', etc.) and distinguishes it from sibling tools like entity_profile through the phrase 'ALWAYS PREFER 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?

Provides explicit when-to-use instructions ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and concrete examples of use cases ('rank these companies', 'head to head'). Clearly states the tool should replace 8-15 sequential lookups, giving strong usage guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description adds minimal behavioral context beyond the output format (image URL). No additional traits like rate limits or costs are mentioned.

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

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

Three concise sentences: action, output, and usage. No redundancy, efficient and front-loaded.

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

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

Given the simple tool with well-documented parameters and an output schema, the description is complete enough for an agent to understand usage 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 both parameters. The tool description does not add additional meaning beyond what is already in the schema.

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

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

The description clearly states the verb 'Generate' and the resource 'QR code', specifying inputs as 'text or URLs'. This distinguishes it from sibling 'read_qr' which decodes QR codes.

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

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

The phrase 'Use when you need to encode information into a QR code' provides clear context for when to use the tool. It does not explicitly mention alternatives or exclusions, but the purpose is well-defined.

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

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

Adds significant behavioral context beyond annotations: requires Pipeworx account, paid plan for thorough depth, expected 15-60s response time, return structure (findings with verbatim evidence, confidence, gaps). 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 verbose but well-organized. Front-loaded with core concept, then details on behavior, usage, and requirements. Every sentence adds value, though could be slightly more concise.

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

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

For a complex tool with no output schema, description fully covers return format (structured findings packet, gaps, citations), prerequisites (account, plan), timing, and alternatives. No missing critical information.

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 meaning: explains depth values (quick=3, standard=5, thorough=8 with paid requirement) and clarifies question should be broad/multi-part. Enhances 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 performs grounded multi-source research in one call, with decomposition into sub-questions and parallel execution. It distinguishes from sibling ask_pipeworx by specifying scope (broad/multi-part vs single lookup).

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: 'for broad or multi-part questions' and when not: 'use ask_pipeworx for single lookups'. Also provides context on account requirements and plan limitations for 'thorough' depth.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 somewhat lengthy due to listing many domains, but it is well-structured with the purpose upfront and key usage statements. Every sentence adds value, though it 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 no output schema, the description fully explains what is returned: top-N tools with names, descriptions, and schemas, ready to call. It also specifies defaults and limits. With 6 parameters (many aliases), the description covers the tool's function completely.

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

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

Schema description coverage is 100%, so baseline is 3. The description does add mention of aliases and that query is the main parameter, but this is already in the schema. No significant added meaning beyond what the schema provides.

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

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

Description starts with a clear verb-resource pair: 'Find tools by describing the data or task.' It explicitly lists many domains it covers, and distinguishes itself from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set.'

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 clearly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools...' It implies not for getting a single answer, but does not explicitly say when not to use it, which prevents a 5.

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

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

Beyond annotations (readOnly, idempotent, openWorld), description adds specific behavioral details: fan-out across multiple sources, patent soft-fail date, and fallback mechanisms. 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 detailed but front-loaded with examples and clear structure. While slightly long, every sentence adds value, and the length is justified by the tool's complexity.

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

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

Given the tool's complexity (multiple sources, no output schema), the description is remarkably complete. It lists return fields, explains fallback behavior, and notes future changes. Missing output schema is compensated by description.

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 critical meaning: names are not supported, use resolve_entity first. This clarifies parameter semantics beyond what the schema alone provides.

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

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

Description clearly states the tool provides a full cross-source profile of a US public company, supported by example queries and a list of returned data. It distinguishes from sibling tools by noting that names are not supported and recommending resolve_entity.

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 guides to prefer this tool over chaining individual lookups for holistic views. It warns that names are not supported and directs users to resolve_entity first. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint and idempotentHint. The description adds behavioral context (clearing sensitive data) but does not contradict annotations.

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

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

Two sentences: first states the action, second provides usage guidance. Extremely concise and front-loaded with essential information.

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

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

Given single parameter, full schema coverage, no output schema, and annotations present, the description completely covers purpose, usage, and pairing without 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 a clear parameter description. The tool description restates the purpose but does not add new parameter semantics beyond the schema.

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

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

The description clearly states the action 'Delete a previously stored memory by key' and distinguishes from siblings by suggesting pairing with 'remember' and 'recall'.

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 when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and notes pairing with related tools.

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

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

Description details process (fetch, extract, emit) which aligns with annotations (read-only, idempotent). Adds context beyond annotations by specifying standard markdown format. No contradictions found.

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

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

Concise three-sentence structure: purpose, process, use cases. Every sentence adds value with 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?

Covers purpose, process, output format, and typical uses for a simple two-parameter tool without output schema. Missing error handling or edge cases (e.g., inaccessible URLs) but adequate for typical use.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add new semantics beyond what schema provides for 'url' and 'max_links'. It mentions extraction but doesn't elaborate on parameter details.

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

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

States specific verb 'generate' and resource 'llms.txt file' with target audience (AI crawlers) and output format. Clearly distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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

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

Provides three explicit use cases (client site indexing, personal project drafting, competitor auditing) but does not mention when not to use it or alternatives from the sibling list.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds context about default filtering to active subscriptions and lists exact return fields, exceeding annotation coverage.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. No unnecessary words.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers purpose, usage, return values, and parameter effect. Complete.

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

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

Schema covers the single parameter with a description (100% coverage). The description adds value by explaining the parameter's effect implicitly (active vs inactive) and listing return fields not in 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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, created_at, last_fired_at, fire_count). It 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 states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This directly guides the agent on appropriate usage and implies alternatives.

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

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

Annotations provide no safety flags (readOnlyHint=false, destructiveHint=false), but the description adds critical behavioral details: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads daily, signal affects roadmap. This goes beyond annotations.

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

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

The description is relatively long but every sentence earns its place. It is front-loaded with purpose and then structured around categories and behavioral notes. No filler. Could be slightly trimmed but appropriate for the information density.

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 (3 parameters, nested object, enum), the description provides all necessary context: usage categories, rate limits, quota info, and message guidelines. No output schema exists, but the description covers what the agent needs 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%, so baseline is 3. The description adds extra guidance on how to write the message (be specific, 1-2 sentences, max 2000 chars) and emphasizes describing in terms of Pipeworx tools/packs. This adds meaningful value over 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 action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It identifies the resource (Pipeworx team) and distinguishes the tool from siblings as a feedback mechanism, unique among the listed tools.

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

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

Explicitly details when to use: for bugs, feature requests, data gaps, praise. Provides examples and even instructs what not to do (avoid pasting end-user prompts). Clearly 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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals data source ('CF analytics-engine'), privacy ('no PII'), output format ('pack, tool, count'), and caching behavior ('cached 5min-1h'). This adds significant behavioral context not captured by annotations alone.

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

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

The description is concise (4 sentences), front-loaded with the primary function, followed by use cases, then technical details. Every sentence is necessary and well-structured, with no redundant or vague information.

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

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

Given the tool's low complexity (1 optional parameter, read-only, idempotent) and no output schema, the description fully covers input semantics, output format, and behavior (caching, data origin). It is complete for effective use.

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

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

The single parameter 'window' has 100% schema coverage with enum values and a description. The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', providing semantic meaning beyond the enum.

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 recent window', with a specific verb ('returns') and resource ('Pipeworx trending data'). It distinguishes itself from sibling tools like 'discover_tools' and 'ask_pipeworx' by focusing on aggregate trends from other agents, not direct queries or exploration.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical tools, checking alignment with agent needs). While it doesn't explicitly say when not to use or name alternatives, the stated use cases provide clear guidance on when this tool is appropriate.

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 numerous behavioral traits beyond annotations (readOnlyHint, openWorldHint, etc.): it explains the monotonicity and partition checks, semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder slugs), and fill check (realizable edge against CLOB depth). It explicitly states when not to trade. 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 fairly long but every sentence adds value. It is front-loaded with the requirement and structured logically. Minor verbosity, but overall appropriately sized 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?

Despite the tool's complexity (two modes, multiple checks, fill check), the description is comprehensive. It details the response structure (opportunities, partition_check, fill check), mentions related tools (polymarket_fill_risk), and covers edge cases (placeholder filter). No output schema exists, but the description compensates adequately.

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 significant meaning: for 'event', it specifies it accepts slugs or URLs and explains the mode; for 'topic', it explains it's a seed question for cross-event scanning. This goes beyond the schema's brief 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: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific use cases. While it doesn't explicitly differentiate from sibling tools like polymarket_edges, the purpose is well-defined and not a tautology.

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: requires one of 'event' or 'topic', explains when to use each mode (recommends event for specific markets, topic for cross-event scanning), and notes that calling with no args fails. It doesn't list alternative sibling tools but gives clear context for when to use each mode.

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

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

The description adds extensive behavioral context beyond the annotations: it explains the different model families, segments, diagnostics, caching behavior ('Cached 1h at the KV level'), and parameter effects. It does not contradict the annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is well-structured with sections (segments, knobs, response) and front-loads the purpose. It is detailed and each sentence adds value. However, its length could be slightly condensed for a 1-5 scale, but the complexity of the tool warrants the detail.

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

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

The description covers all aspects of the tool: purpose, model families, tradeable-edge knobs, response structure (by_segment, diagnostics), caching, and parameter effects. Despite no output schema, it explains the response fields and segments sufficiently. For a complex tool with 9 parameters, this is complete.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra context for some parameters (e.g., 'max_spread_pp' suggests setting to 2 for tight books), enhancing understanding beyond the schema. Baseline is 3 due to high coverage, but the additional guidance justifies a 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is specific about the resource (Polymarket markets) and the action (scan and return opportunities), and distinguishes it from siblings by emphasizing no need to page hundreds of markets.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the tradeable-edge knobs and their use, but does not explicitly state when to use alternatives among siblings (e.g., polymarket_arbitrage) or 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 already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: data source (daily snapshots), computation details (trend, decay), and limits (60-day TTL). 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 detailed but well-structured with a lead sentence and bullet-pointed response fields. While somewhat long, every sentence adds value, and the structure aids readability.

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

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

Despite no output schema, the description thoroughly explains the response structure, including tracked[], expired[], and snapshot_dates[]. It covers key aspects like trend computation and data gaps, making it complete enough for an agent.

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

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

Schema coverage is 100% with descriptions, but the description adds context: default values (14 days, '1wk') and max clamp (30 days). This enriches the schema info without being redundant.

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

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

The description explicitly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and clearly distinguishes from siblings like polymarket_edges, which likely focuses on current edges.

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

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

The description implies usage for historical edge analysis but does not explicitly state when to use this tool versus alternatives. It provides no 'when not to use' guidance or specific alternatives, though the context of sibling tools suggests differentiation.

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 include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: it explains the tool walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and warns that partial basket fills convert an arb into an unhedged directional position. No contradiction with annotations.

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

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

The description is well-structured with sections for modes and usage guidance, and it is front-loaded with the purpose. While it is somewhat lengthy, every sentence adds value. Minor redundancy could be trimmed but overall efficient.

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

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

Given the tool's complexity (two modes, multiple output fields), no output schema, and rich annotations, the description covers key inputs, outputs, usage guidance, and risks. It mentions specific output fields like top_of_book, vwap_fill_price, etc. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining how parameters behave in single-market vs basket modes, the default auto behavior for side, and the interpretation of size_usd as 'settlement notional' for baskets. This additional context justifies a score above 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It differentiates between single-market and basket modes, and provides a specific use case distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly tells when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risks of partial fills and why this check is necessary, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds critical behavioral details: compatibility_warning conditions (bet shape non-equivalence or semantic mismatch), temporal alignment check, skipped cross-type/subtype counters, and the condition that spreads are 'mathematically meaningless' if not aligned. 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 dense but well-structured with sections for modes, response, and safety fields. It is front-loaded with the core purpose. While lengthy, every sentence adds necessary behavioral or usage context. Could be slightly more concise, but not overly verbose.

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 spread with potential mismatches), 3 parameters, no output schema, and basic annotations, the description provides comprehensive context: response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment, skipped counters), and caveats about tradeability. An agent can fully understand when and how to use the tool and interpret results.

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

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

Schema covers 100% of 3 parameters with descriptions, but the description adds substantial meaning: explains the two modes (topic vs explicit), lists all 10 pre-mapped shortcuts, and clarifies that explicit overrides topic mapping. This adds value beyond the schema alone.

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

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

The description clearly states the tool's purpose as 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It identifies the specific verb (compute spread) and resource (two prediction markets), distinguishing it from sibling tools like polymarket_arbitrage (intra-venue) and polymarket_edges (likely edge detection).

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

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

Explicitly describes two modes ('topic' shortcuts and explicit event identifiers) and when to use each. Warns that most pre-mapped topics return compatibility_warning, guiding agents to check before relying on spreads. Also states that real spreads are rarer than the shortcut list suggests, indicating when not to expect tradeable opportunities.

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 strong safety signals (readOnlyHint, idempotentHint, destructiveHint=false). The description adds that it returns decoded content, but does not add further behavioral context such as constraints on image formats or rate limits. Given annotation coverage, this is adequate but not enriched.

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

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

The description is two sentences, front-loaded with purpose, and contains zero wasted words. It is highly concise and 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 tool with one parameter, full schema coverage, and strong annotations, the description is nearly complete. It could mention output details or file format constraints, but the existing information is sufficient for an AI agent to understand the tool's purpose and usage.

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

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

Schema coverage is 100% with a clear parameter description. The tool description does not add additional meaning beyond what the schema already 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?

The description clearly states the verb 'decode', the resource 'QR code images', and the result 'extracted text or URLs'. It distinguishes from sibling 'create_qr' which performs the opposite operation.

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 context: 'Use when you need to read what's stored in a QR code.' While it doesn't explicitly state when not to use it, the context is clear and the sibling tool 'create_qr' provides a natural alternative.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds the dual behavior (retrieve vs. list) and scoping. Does not contradict annotations. Could mention behavior on missing key, but still clear.

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

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

Three sentences, front-loaded with primary action. Each sentence adds value (operation, usage context, scoping, sibling pairing). No extraneous 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?

No output schema, but description explains what is returned (value or list of keys). However, it doesn't specify format or behavior for missing keys. Sibling tools are mentioned, providing context. Adequate for a simple retrieval tool.

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

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

Schema coverage is 100% and already describes the key parameter's behavior. Description repeats this without adding new semantics. 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 retrieves a value by key or lists all keys, and it's for looking up previously stored context. It distinguishes from siblings like remember and forget by mentioning them explicitly.

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

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

Provides explicit guidance: use to look up stored context without re-deriving, and mentions scoping to user identifier. Also notes pairing with remember to save and forget to delete, and that omitting key lists all keys.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context: the returned data format, the mark_read behavior (flagging events read so next call shows newer ones), and the ability to poll. 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 four sentences, front-loaded with the core purpose. Every sentence serves a distinct purpose: stating what it does, listing key fields, explaining filtering/mark_read, and providing an alternative access method. 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?

Despite having no output schema, the description clearly explains what is returned (source, citation_uri, raw payload). It covers all 5 parameters indirectly through examples and effectively describes the tool's behavior for both single calls and polling. The alternative URL adds completeness.

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 concrete examples (e.g., 'sec_8k' for type) and explains the effect of mark_read ('flag returned events read so the next call only shows newer ones'), providing semantic value beyond the schema definitions.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', with specific details about the returned data (source, citation_uri, raw payload). It distinguishes from sibling tools like 'list_subscriptions' by focusing on alerts, not subscriptions.

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

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

The description explains filtering by type and since, the effect of mark_read, and that polling works fine. It also points to an alternative URL for scripts/dashboards. However, it does not explicitly mention when not to use this tool or compare to siblings beyond the context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context beyond these: internal fan-out to SEC EDGAR, GDELT/GNews fallback, USPTO soft-fail, date parsing, and return structure (changes[], total_changes, citation URIs). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the core purpose with common query examples. It then lists sources, parameter details, and alternative usage. While dense, every sentence adds necessary context; minor improvement could be breaking into bullet points for readability.

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

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

Given the tool's complexity (multiple sources, fallback logic, date parsing) and the absence of an output schema, the description covers all essential aspects: purpose, sources, parameter formats, return structure, and sibling distinction. No gaps identified.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the since parameter formats (ISO date and relative shorthand with examples) and recommending '30d' or '1m' for typical monitoring. It also explains the value parameter accepts ticker or zero-padded CIK. These details go beyond the 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 explicitly states the tool's purpose: answering queries like 'What's new with X' by providing a change feed for a company. It distinguishes from sibling entity_profile by specifying when to use the alternative for static profiles. The verb-resource relationship is clear and 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 explicit when-to-use guidance with examples of common queries and directly names the alternative tool entity_profile for static profiles. It also explains the fan-out to multiple sources and the fallback behavior, giving clear context for usage decisions.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds context: scoping by identifier, authentication-based persistence, and 24-hour retention for anonymous sessions, going beyond annotations.

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

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

Two concise sentences front-loaded with purpose. Every sentence adds value 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?

For a simple key-value write tool with no output schema, the description fully covers storage mechanics, scope, persistence, and pairing with recall/forget.

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 provides example keys ('subject_property', 'target_ticker') and clarifies the value is 'any text,' adding semantic guidance.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies the verb (save/resource (data)) and distinguishes from siblings like 'recall' and 'forget'.

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

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

Explicit usage guidance: 'Use when you discover something worth carrying forward.' Contrasts with 'recall' and 'forget' for retrieval and deletion, and explains session persistence differences.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds value by explaining internal cascading behavior and specifying citation URIs for each entity type, which aids agent understanding of the tool's behavior.

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

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

The description is front-loaded with the core purpose and example queries, then systematically details supported types. No redundant sentences; every sentence adds value, making it concise yet comprehensive.

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

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

With no output schema, the description fully compensates by explicitly listing the return fields for each entity type. It also addresses auto-disambiguation and citation URIs, providing complete context for an agent to use the tool effectively.

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

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

The input schema covers 100% of parameters with descriptions. The description adds significant meaning by detailing return values (ticker, CIK, citation for company; RxCUI, ingredient, citation for drug) and clarifying acceptable input formats for 'value', going well 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 opens with explicit example queries and clearly states the tool resolves a name to an identifier. It distinguishes supported types (company, drug) with detailed outputs, and the phrase 'Use FIRST whenever you have a name but need an ID' differentiates it from siblings.

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

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

The description explicitly tells when to use the tool ('Use FIRST...') and notes it replaces 2-3 manual lookups. It lacks explicit when-not-to-use scenarios, but the priority placement provides strong guidance.

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

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

Annotations already declare safe read-only, idempotent behavior. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density per entity. This provides useful behavioral context beyond annotations.

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

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

Description is four sentences, each serving a distinct purpose: purpose, process, use case example, return format. No fluff, well-structured, and front-loaded with key info.

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

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

For a tool with 4 parameters and no output schema, the description explains what it does, how it works, what it returns (ranked list with fields), and gives an example use case. It is complete and self-contained.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor value: it notes first entity is treated as 'subject' for narrative, which is not in schema. Otherwise, parameter details are already in schema descriptions.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks them by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (broader 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 explicitly gives use case: competitive AI-marketing audits. It implies this tool is for multi-entity comparison, but does not explicitly state when not to use or mention alternatives (e.g., ai_visibility_check for single entity). Still, context is clear enough.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. Description adds valuable context: fans out across multiple sources, partial failures with sources_failed, timing for bundlephobia first measurement (5-30s). 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 thorough but front-loaded with core purpose. Every sentence adds value, though slightly lengthy. Well-structured and informative without redundancy.

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

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

Given no output schema, description lists specific return fields and contents. Covers ecosystem scope, partial failures, timing, and scoped packages. Complete for a composite tool with 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% with good descriptions. Description adds minor extra detail (scoped packages accepted, version defaults to latest), but does not significantly expand beyond 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?

Clearly states it's a composite check for npm packages across multiple sources (deps.dev and bundlephobia), specifying what it evaluates (license, advisories, size, tree-shake support). Distinguishes from siblings by noting ecosystem limitation and alternatives for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and provides when-not-to-use by saying NPM ecosystem only in v1, others fall under deps.dev:version directly. Also mentions graceful degradation and partial failures.

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 behavioral details beyond annotations: uses BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation flag, and that each passage includes character offsets for verification. Annotations already indicate read-only and idempotent, and description adds context.

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

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

Concise, front-loaded sentences: first sentence states purpose, then usage, then technical details. Every sentence adds value with zero 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 explains return format (passages with offsets and scores), embedding model, windowing, and truncation behavior. All three parameters are fully documented with usage context.

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

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

Schema description coverage is 100%, so baseline 3. The description adds value by providing natural-language query examples and clarifying the text parameter's max size, but the schema already conveys similar info. The extra context about output offsets is beneficial but pertains to return values.

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 'Semantic search INSIDE a fetched record' with a specific verb+resource. It distinguishes itself from siblings like ask_pipeworx_grounded by explaining how it pairs and when to use it, e.g., when records are too large for the prompt.

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') and provides an alternative ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document').

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 it's not read-only, not destructive, idempotent, and open world. The description adds behavioral details like account requirement, delivery channel constraints (10/day SMS cap, webhook auto-disable after 10 failures), and that the webhook secret is returned once. No contradictions.

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

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

The description is well-structured, starting with the core purpose, then detailing types and delivery. It is comprehensive but could be slightly more concise; however, every sentence adds value.

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

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

Given the complexity (3 params, nested objects, no output schema), the description is thorough. It covers all subscription types, their parameters, delivery options with constraints, and mentions the return of a subscription id. 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%, so baseline is 3. The description provides extensive context beyond the schema: details for each subscription type with examples, delivery channel options with constraints (e.g., phone verification, rate limits), and the webhook HMAC signature process. This greatly enhances 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 creates a proactive monitoring subscription to a live-data event stream, returns a subscription id, and distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. The verb 'create' and resource 'subscription' 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 context for when to use (creating subscriptions for specific event streams) and mentions a prerequisite (Pipeworx OAuth account). It does not explicitly state alternatives or when not to use, but the sibling tools cover other operations.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds context about returning live tool+argument shapes. Value added but not dramatically beyond annotations.

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

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

Description is comprehensive but slightly long; well-structured with common queries at start and parenthetical lists. Could be tighter but remains effective.

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 role as onboarding entry point with many siblings, the description fully covers purpose, usage, parameter, and return expectations despite no 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 coverage 100% with one optional parameter. Description explains topic values and usage with examples, adding meaning 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 returns category-bucketed example questions and serves as the onboarding entry point. Distinguishes from siblings by mentioning meta-tools like ask_pipeworx, entity_profile, etc.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and provides guidance on when to use alternatives like meta-tools. Also explains optional topic filtering.

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 high-level hints (idempotent, non-destructive), while the description adds critical context: ownership enforcement, deactivation semantics, and data availability via recent_alerts.

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

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

Two sentences, no wasted words. The action is front-loaded, and every sentence adds essential information.

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

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

The description fully covers the tool's purpose, ownership constraint, side effects (deactivation vs deletion), and cross-references a sibling tool (recent_alerts). Incomplete only if output schema needed, but not expected here.

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 a clear description for the 'id' parameter. The tool description reinforces that this is the subscription id returned by subscribe, adding context beyond the schema.

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

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

The description states the action ('Cancel a subscription by id') with a specific verb and resource, and immediately clarifies ownership enforcement, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description clearly states when to use ('only your own subscriptions') and provides behavioral context (deactivation, not deletion), but does not explicitly mention alternatives or 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?

Descriptions adds significant behavioral context beyond annotations: return types (verdict categories, extracted form, actual value with citation, percent delta), data sources (SEC EDGAR + XBRL), and what the tool does internally. 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?

Well-structured with trigger phrases first, then functional description, limitations, and return details. Slightly long but each sentence adds value. 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?

Given the single parameter and no output schema, the description fully covers the tool's purpose, usage, input format, output structure, and scope. It also explains how it replaces multiple sequential calls, providing complete context for an agent.

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

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

Schema coverage is 100% (one well-documented parameter). Description adds value beyond schema by explaining the domain of supported claims (company-financial) and providing example formats, which helps the agent formulate the claim 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?

Description clearly states it's for natural-language claim verification using authoritative sources, with explicit trigger phrases and specification that it handles company-financial claims. Distinguishes itself from siblings by noting it replaces 4-6 sequential calls.

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

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

Explicitly says 'use whenever the agent needs to check whether something a user said is factually correct.' Also specifies scope: company-financial claims for public US companies. While it doesn't explicitly list when not to use, the limitation provides clear guidance.

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