Todoist

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

Annotations (readOnly, idempotent, non-destructive) are already present. The description adds valuable context: default model is free (Workers AI), probing Anthropic requires BYO key with direct payment, and the return structure (per-model score, confidence, signals, raw response plus combined view). 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 concise (4 sentences) and front-loaded with the main action and scoring range. Every sentence adds value: purpose, default behavior, return format, use cases. No redundant or vague phrasing.

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 4 parameters with full schema descriptions, no output schema but description explains return structure, and annotations covering safety, the description is mostly complete. It could mention that results are not persisted (implied by readOnly) or that it's a real-time probe, but overall sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: explains default model for 'models' parameter, notes that omitting models uses only workers-ai, and clarifies that _apiKey is passed through to Anthropic. This enhances understanding 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 clearly states the tool probes LLMs for knowledge about a business or topic and scores visibility (0-100). It specifies the verb (probe, score) and resource (LLMs, visibility). However, it does not explicitly differentiate from similar sibling tools like scan_competitor_ai_presence, which might also measure AI visibility.

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

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

The description gives use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default model and optional API key for Anthropic. However, it does not specify when not to use this tool or mention alternatives among the 32 siblings, leaving some guidance gaps.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the routing behavior to 4,476 tools, the structured nature of the response, and the stable citation URIs. No contradictions with annotations; the description enhances transparency without repeating annotation info.

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 starts with a clear preference directive, lists supported domains, gives usage examples, and compares with siblings. It could be slightly tighter, but it is well-structured and front-loaded. Minor redundancy in listing all the alias parameters could be trimmed.

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

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

Given the tool's complex role of routing to many sources, the description is remarkably complete. It covers what it can answer, how it works (one fast call), when to use it vs. alternatives, and the citation format. No output schema is needed because the description explains the return value sufficiently. All aspects are addressed.

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

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

Schema coverage is 100% with all 6 parameters documented. The description does not add new parameter-level details beyond what the schema provides, but the schema's description is sufficient ('Your question or request in natural language'). The description supplements by showing examples of what constitutes a valid question. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it routes factual questions to a large set of authoritative sources and returns structured answers with citations. It gives numerous examples and distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its purpose unmistakable.

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

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

The description explicitly recommends this tool over web search for a wide range of factual queries, provides specific trigger phrases ('look up', 'find', etc.), and clearly states when to step up to alternative tools (for hallucination-resistant answers or multi-part questions). This gives the agent precise guidance on when to invoke this tool vs. others.

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

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

While annotations already mark the tool as readOnly, idempotent, and non-destructive, the description adds critical behavioral details: it extracts answers only from tool results, returns explicit refusal reasons, and describes the exact return format with fields like 'answer', 'evidence', 'confidence', etc. 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 relatively long (3-4 sentences) but front-loaded with the core purpose. Every sentence adds value, including usage guidance, behavioral details, and return format. Could be slightly more concise, but the structure is logical and efficient 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?

Given the tool's complexity (grounded mode with explicit refusal), no output schema, and 6 parameters, the description is complete. It explains the refusal reasons, return format, and when to use vs. sibling. The agent has enough information to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it only mentions 'same routing as ask_pipeworx... fills arguments' without elaborating on parameter semantics or usage. The aliases are already listed 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from its sibling 'ask_pipeworx' by explaining the extraction-only behavior. The verb 'ask' and resource 'Pipeworx' are clear, and the scope is well-defined.

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 ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete examples (financial verdicts, legal claims, medical lookups, public statements). Also contrasts with sibling 'ask_pipeworx' by noting the extra LLM cost and advising 'prefer ask_pipeworx for casual lookups'.

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

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

The description extensively details behavioral traits beyond annotations. It covers safety short-circuiting on low-confidence matches, closed market handling, wide-spread tradeability notes, resolution-rule risk parsing, and response shapes. Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds deep context without contradiction.

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

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

The description is dense but well-structured: front-loaded with purpose and inputs, followed by examples, response shapes, safety notes, and edge cases. While long, every sentence adds necessary detail for a complex tool. It could be slightly tightened, but it earns its length.

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

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

The description covers all relevant aspects: input flexibility, fan-out logic, response shapes, safety mechanisms, resolution rules, and caveats (e.g., closed markets, wide spreads). Without an output schema, the detailed description of return fields and edge cases ensures agents understand what to expect.

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 value by explaining how depth ('quick' vs 'thorough') and include_raw affect the fan-out and response size, with concrete examples. This goes beyond the schema definitions and 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 researches a Polymarket bet by pulling Pipeworx data. It specifies the input types (slug, URL, question text) and output (evidence packet, market-vs-model comparison). It distinguishes its purpose from sibling tools like polymarket_edges and polymarket_arbitrage by framing use cases like 'should I bet on X'.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and gives detailed fan-out examples by category. While it does not explicitly state when not to use or list alternatives, the context of sibling tools and the clear use cases offer sufficient 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?

Discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. These details go well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) providing agent with critical behavioral context.

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

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

Well-structured with trigger phrases upfront, then core purpose, usage priority, type-specific details, sorting behavior, and return format. Every sentence adds value; no redundant or vague statements.

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 (2 parameters, no output schema), the description thoroughly covers behavior, data sources, and return format (paired data + citation URIs). Also highlights replacement of 8-15 sequential lookups, aiding the agent in deciding when to 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?

Adds significant meaning beyond the input schema: explains what each entity type returns (10-K data for companies, adverse events for drugs), format of values (tickers/CIKs vs drug names), and example values. Schema coverage is 100% but the description enriches understanding.

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

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

Clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. Specific verb 'compare' and resource 'entities' with examples of trigger phrases. Differentiates from siblings like entity_profile that handle single entity lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives example phrases. Does not explicitly state when not to use, but the constraint of 2-5 entities implies exclusion of single entity queries. Still clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds crucial behavioral context: returns 'findings packet' with verbatim evidence, confidence, source, fetched_at, and stable citations; includes 'explicit gaps[]' for unanswered facets; warns of 15-60s latency; and states it 'never invented' data. 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 moderately long but front-loads critical information (account requirement, alternative). Each sentence adds value, though some details like exact source count and tool count are possibly excessive. Structure is logical with clear separation of prerequisites, behavior, and usage guidance.

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

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

Given the tool has no output schema, the description compensates by explaining the return format (findings packet with evidence, gaps, citations) and behavior. It also clarifies limitations for breaking news and the parallel search approach. For a 2-parameter tool with no output schema, the description is comprehensive.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds context by explaining the depth enum values (quick=3, etc.) and that the question is decomposed into facets. While schema already covers basics, the description enriches understanding marginally beyond baseline.

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

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

The description clearly states the tool does 'grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' and distinguishes it from open-web search. It provides specific examples of when to use ('compare X and Y's regulatory + financial exposure') and explicitly contrasts with sibling tool ask_pipeworx.

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

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

The description gives explicit guidance on when to use (broad/multi-part questions over structured data) and when to avoid (breaking news, single lookup), and names the alternative (ask_pipeworx). It also includes account requirements and the depth parameter's plan dependency.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds value by specifying the output format: returns top-N tools with schemas and curated examples, ready to call directly. This goes beyond annotations but does not contradict them.

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

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

The description is concise (about 100 words) and front-loaded with the main action. Every sentence adds value: purpose, usage guidance, output details. No redundant or filler content.

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

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

Given the tool's simplicity (6 parameters, no output schema), the description is complete. It explains what the tool does, what it returns, and how to use it. The absence of an output schema is compensated by the description detailing the result content.

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

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

Schema coverage is 100% with all parameters described, including aliases. The description provides example queries (e.g., 'analyze housing market trends') but does not add significant semantics beyond what the schema already conveys. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific examples of domains (e.g., SEC filings, FDA drugs) and distinguishes itself from sibling tools as the meta-discovery tool. The verb 'Find' and resource 'tools' 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?

The description explicitly instructs when to use this tool: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond these: details on what the tool returns (cik, company_name, filings, fundamentals, patents, news, LEI), mentions the USPTO PatentsView API sunset and soft-fall behavior, and describes its fan-out across multiple sources. 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 appropriately long for the complexity, but well-structured with example queries upfront, followed by sources and return information. Every sentence adds value; no redundancy. It front-loads the key usage pattern.

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

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

Given no output schema, the description covers return fields and data sources well. It mentions that fundamentals include LATEST 10-K Revenues etc., but does not specify the exact JSON structure. For a tool of this complexity, it is nearly complete, but a minor gap is the lack of explicit output format details.

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

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

Schema description coverage is 100%, but the description adds significant meaning: it clarifies that 'type' is currently limited to 'company', and 'value' can be ticker or zero-padded CIK, with an explicit warning about unsupported names and a recommendation to use 'resolve_entity' first. 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: providing a comprehensive cross-source profile of a US public company. It includes example queries ('Tell me about X', 'brief me on Tesla') and lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It effectively distinguishes itself from siblings like 'resolve_entity' (for name resolution) and 'compare_entities' (for comparison).

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

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

The description provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clearly states when not to use: 'names not supported (use resolve_entity first if you only have a name).'

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description states 'Delete', aligning with destructiveHint, but adds no further behavioral details beyond what annotations and schema provide.

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

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

Two sentences, no filler, front-loaded with the core action. Every sentence serves a purpose.

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

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

For a simple tool with one parameter, no output schema, and informative annotations, the description fully covers purpose and usage 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%, and the description mentions 'by key', but adds no additional meaning beyond the schema's description of the 'key' parameter.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb and resource. It distinguishes from sibling tools like 'remember' and 'recall' by mentioning pairing.

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

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

Explicit usage scenarios are given: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also hints at alternatives by mentioning 'Pair with remember and recall.'

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 process: fetching the page, extracting title/description/key links, and emitting standard markdown format. Adds significant context beyond annotations (readOnlyHint, idempotentHint) that already indicate safe, read-only operation.

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

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

Three sentences: purpose, process, use cases. Front-loaded with main action. No filler, each sentence adds value.

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

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

Given no output schema, the description adequately explains output as 'single text blob' and mentions format. Could mention error handling or rate limits, but sufficient for a simple fetch-and-format tool.

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

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

Schema covers both parameters (url, max_links) with descriptions. The description adds real-world examples for url (e.g., 'https://example.com' or a specific landing page) and default/max constraints for max_links (default 25, max 50), enhancing usability.

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 generating a production-ready llms.txt file for any URL, specifies verb, resource, and scope, and distinguishes from sibling tools like ai_visibility_check by focusing on generation rather than checking.

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 use cases (client indexing, own project drafting, competitor auditing), giving clear context for when to use. Lacks explicit exclusions but sufficient for typical needs.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return fields but doesn't 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 concise sentences with clear structure, listing fields and usage.

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 low complexity (one optional param, no output schema), description is complete and sufficient.

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

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

Schema coverage 100%, description adds no additional meaning beyond schema's parameter description.

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

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

Description explicitly states 'List the caller's active subscriptions' and lists return fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel' clearly tells when to use.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, etc. The description adds behavioral context beyond annotations: rate limit of 5 per identifier per day, that it is free and doesn't count against tool-call quota, and that the team reads digests daily. This adds meaningful transparency.

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

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

The description is a single paragraph of about 100 words, which is concise but could be more structured (e.g., bullet points for use cases). Every sentence adds relevant information 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 the tool's simplicity (sending feedback) and the detailed input schema with 100% coverage, the description covers purpose, usage guidelines, parameter use, and behavioral constraints (rate limit, quota). No output schema is needed. The description is complete for effective tool selection and invocation.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description adds value by advising to describe issues in terms of Pipeworx tools/packs and not to paste the end-user prompt, which is not in the schema. This extra guidance enhances parameter semantics.

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

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

The description clearly states the tool's purpose: to send feedback about bugs, feature requests, data gaps, or praise. It lists specific triggers (wrong/stale data, missing tools, positive experiences) and distinguishes itself from sibling tools, none of which target feedback.

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

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

The description provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and a clear what-not-to-do instruction (don't paste end-user prompt). It does not explicitly mention when not to use, but the context is sufficient given no alternative feedback tools exist among siblings.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable details: data source (CF analytics-engine), no PII, caching duration (5min-1h). No contradiction.

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

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

Four sentences, front-loaded with core functionality, then use cases, then provenance. Every 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 one parameter, no output schema, and clear annotations, the description is complete. It explains what is returned, parameter options, use cases, and caching behavior.

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 enum and description. The description adds interpretation: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds value beyond schema.

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

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

Description clearly states the verb 'returns' and the resource: top tools, top packs, and total call volume. It also distinguishes itself from siblings by focusing on trending data.

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

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

Three explicit use cases are provided, giving clear context on when to use the tool. However, it does not explicitly say when not to use or mention alternatives, but the use cases are sufficient.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral details: required parameters, semantic anchor for cross-event pairs, partition filter, fill check, and response structure. 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 informative but verbose, with multiple paragraphs and detailed internal logic. It is well-structured with front-loaded requirements, but could be more concise to improve readability.

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

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

Given no output schema, the description adequately explains return values (opportunities[], partition_check) and covers both modes. It addresses edge cases like low similarity and placeholder fractions, making it complete for agent use.

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

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

Both parameters have descriptions in the input schema (100% coverage), and the description elaborates with examples and context for each mode, adding significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose as finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, and the sibling tools list includes related tools like polymarket_fill_risk, polymarket_edges, confirming differentiation.

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

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

The description provides explicit guidance on when to use each mode: event mode for a specific market, topic mode for cross-event scanning. It includes examples and notes that calling with no args fails. However, it does not explicitly state when not to use the tool or when to prefer siblings, which slightly lowers the score.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds significant behavioral context: caching at the KV level keyed on all knobs, the structure of the response including diagnostics for empty segments, and details on how edge is calculated. It also explains the tradeable-edge knobs and their effects, providing transparency beyond what annotations offer.

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

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

The description is long but well-structured: it begins with a clear purpose, then details each model family, output structure, and parameters. It is front-loaded with the core value proposition. While some detail could be streamlined, the length is justified by the complexity of the tool.

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

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

Despite having no output schema, the description fully explains the response structure (by_segment, fed_candidates, _diagnostics) and the metrics returned (edge_pp_net, kelly_fraction, etc.). It covers caching, tradeable-edge knobs, and why segments might be empty, making the tool's behavior completely understandable.

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

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

With 100% schema coverage, the baseline is 3. The description enriches parameter meanings by providing context for defaults (e.g., slipping_pp suggests typical values), usage suggestions (e.g., set max_spread_pp to 2 for tight books), and clarifications (e.g., min_edge_pp is net of slippage). This goes beyond the schema's 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for 'what should I bet on today' and details three distinct model families, making its function clear and differentiating from sibling tools like polymarket_arbitrage by covering model-driven and concentrated longshot opportunities.

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

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

The description clearly implies when to use the tool (for discovering betting opportunities without paging hundreds of markets) and mentions configurable knobs for filtering. However, it does not explicitly state when not to use it or provide direct comparisons to sibling tools like polymarket_arbitrage, limiting 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=true and destructiveHint=false, so the tool is safe. The description adds significant behavioral details: what the response contains (tracked, expired, snapshot_dates), how decay is computed (from daily closes, not intraday), and limitations (TTL, gaps). This goes well beyond the annotations.

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

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

The description is dense but well-organized: purpose first, then response structure, then limits. Every sentence adds value. It is longer than typical but justified by the complexity. No fluff, but could be slightly more structured with bullets or sections.

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

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

No output schema exists, so the description must cover return values. It thoroughly explains each part of the response (tracked, expired, snapshot_dates) including computed fields like trend and decay. Limitations are also addressed. The description leaves no ambiguity about what the tool returns.

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 both parameters with descriptions. The description restates them with defaults and max for days, but adds minimal new meaning beyond the schema. With 100% schema coverage, 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 it provides 'edge persistence and decay telemetry' and answers a specific question about edge duration. It uses a specific verb ('answers') and contrasts fresh vs old edges, distinguishing it from the sibling 'polymarket_edges' which likely provides current edge data.

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

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

The description gives context on when to use this tool (to differentiate between fresh and old wide edges) and provides limitations (60-day TTL, snapshot gaps). However, it does not explicitly name alternative tools or state when not to use it, so it's not 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?

Annotations already declare read-only and idempotent; description adds that it 'walks the ladder' and returns verdicts, plus caveats about partial fills. No contradictions. Could mention that no trades are executed, but context implies it's a check.

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 well-structured paragraphs front-load purpose and method. Every sentence adds value, though slightly verbose for the parameter details. Efficient 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?

Covers modes, parameters, return fields, and usage advice. Lacks output schema but enumerates field names. Error conditions not described, but acceptable for this scope.

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

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

Schema coverage is 100%; description adds meaning by explaining mode behavior (market vs event), auto-detection for side, and interpretation of size_usd across modes. This exceeds schema detail.

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

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

The description clearly defines the tool as a fill-risk check comparing realizable vs theoretical edge on Polymarket CLOB depth. It distinguishes single-market and basket modes and lists specific return fields, making it distinct 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?

Explicitly states when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains why (thin books, partial fills causing directional risk), providing clear context and exclusions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds critical context: when bet shapes are equivalent the delta is a real signal, otherwise the tool says so. It explains safety fields like compatibility_warning, temporal_alignment, and skipped counters, which annotations do not cover. No contradictions.

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

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

The description is front-loaded with core purpose, then detailed sections. It is comprehensive but not excessively verbose; every sentence adds value. Slightly longer than needed, but still efficiently structured.

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

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

Given the complexity (two venues, multiple modes, safety fields) and no output schema, the description explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning conditions). It could be clearer about whether top_spreads_pp is an array or single value, but overall it provides sufficient context for an agent to understand the tool's 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%, but the description greatly enhances understanding by explaining the two modes, how topic and explicit parameters interact (explicit overrides topic-mapped side), and provides concrete examples like 'KXFED-26OCT'. This adds significant semantic value beyond the schema.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from siblings like polymarket_arbitrage. It uses specific verbs like 'compute' and 'return', and names the two venues. The purpose is unambiguous and actionable.

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 two modes (topic and explicit) with examples and warnings. It explains when to use each, lists the pre-mapped shortcuts, and cautions that most topics currently return compatibility warnings, setting realistic expectations for the agent.

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

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

Annotations already declare read-only and idempotent behavior; the description adds that it is scoped to an identifier and pairs with remember/forget, enhancing transparency 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 two concise sentences plus a scoping note, front-loaded with the core action, and every sentence serves a purpose.

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

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

For a simple retrieval tool with no output schema, the description covers the two main modes and scoping; missing details on error handling but adequate overall.

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

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

With 100% schema coverage, the description adds value by explaining the effect of omitting the key (listing all keys) versus providing it (retrieving a single value), integrating parameter behavior into tool usage.

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

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

The description uses specific verbs 'retrieve' and 'list' to describe the tool's actions on memory keys, clearly differentiating it from sibling tools 'remember' and 'forget'.

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

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

It provides clear context for when to use the tool (retrieving stored context like user info) and mentions scoping, but does not explicitly state when not to use it.

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

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

Annotations already provide safety hints (readOnly, idempotent, non-destructive). Description adds valuable behavioral details: the effect of mark_read, polling suitability, and alternative access. 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 concise (3-4 sentences) with the purpose front-loaded. Every sentence adds relevant information without fluff or repetition.

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 5 optional parameters and no output schema, the description adequately covers usage, including field details, filter options, polling, and alternative access. Slight gap: no mention of return order or pagination, but limit parameter hints at pagination.

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 provides an example filter type ('sec_8k') and explains mark_read behavior, but does not add substantial new meaning beyond what the schema descriptions already convey.

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 verb ('Pull') and resource ('fired events from your subscription feed'). It specifies what each alert carries (source, citation_uri, raw event payload) and mentions filter options. Differentiates from siblings by its specific focus on recent alerts rather than subscriptions or changes.

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

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

Description provides clear context for use (polling for recent alerts) and mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like 'list_subscriptions' or 'recent_changes', leaving some ambiguity about when to use which.

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. The description adds details about parallel data source fan-out, fallback logic, USPTO deprecation, and return format (grouped changes, total_changes, URI citations). 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 front-loaded with example queries. While somewhat lengthy, every sentence adds value. Could be slightly more concise but still well-structured.

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

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

Given there is no output schema, the description adequately covers return structure (changes grouped by source, total_changes, citation URIs). It also mentions when to use and not use the tool, including alternatives.

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

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

Schema has 100% coverage with descriptions. The description adds value by clarifying `since` accepts relative shorthand ('7d', '30d') and ISO dates, and `value` accepts ticker or CIK. The examples further aid interpretation.

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

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

The description clearly states that the tool provides a change feed for a company over a time window, listing multiple data sources (SEC, GDELT/GNews, USPTO) and giving example queries. It explicitly distinguishes from the sibling 'entity_profile' tool.

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

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

The description gives explicit when-to-use scenarios ('What's new with X', 'latest on Y') and provides a direct alternative ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior for GDELT→GNews and USPTO soft-fail.

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 value beyond annotations by explaining key-value scoping by identifier and persistence rules (authenticated users persistent, anonymous 24h). 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?

Three sentences front-loading purpose and usage; no extraneous words. Could be slightly more structured but effectively 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 simple key-value write tool, the description covers purpose, usage, scoping, persistence, and pairing with sibling tools. No output schema, but that is acceptable for a write operation.

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; the tool description adds only slight context like example key patterns, not enough to significantly improve parameter understanding beyond the schema.

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

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

The description clearly states the verb 'Save' and the resource 'data', and distinguishes the tool from siblings like recall and forget by focusing on storage across conversations and sessions.

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 clear guidance on when to use ('when you discover something worth carrying forward') and references siblings (recall, forget) for retrieval and deletion, but lacks explicit when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds valuable behavior: 'each call cascades through several lookup endpoints internally' and specifies return formats with citation URIs, 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?

The description is compact yet comprehensive: starts with natural-language example queries, states purpose, then details each type with outputs. Every sentence adds value, and the structure is front-loaded and scannable.

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

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

Despite no output schema, the description fully explains return values for both entity types (ticker, CIK, RxCUI, etc.), mentions auto-disambiguation, and includes citation URIs. It leaves no ambiguity about what the tool returns.

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%. Description adds concrete examples for both parameters (e.g., 'ticker (AAPL), CIK (0000320193), or name') and explains what each type returns, providing meaning beyond the schema.

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

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

The description clearly states it resolves names to canonical identifiers with specific examples ('What's the ticker for...'), lists supported types (company, drug), and explicitly says 'Use FIRST whenever you have a name but need an ID', distinguishing it from sibling tools.

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

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

It provides clear context: 'Use FIRST whenever you have a name but need an ID' and notes it replaces manual lookups. However, it does not explicitly mention when not to use or name alternative tools, though the context is strong.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds context about the process (probes, ranks, surfaces) and return data (score, confidence, signal density), enhancing transparency 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 three sentences with clear, front-loaded purpose and no fluff. Every sentence adds value, making it 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?

Given 4 parameters, no output schema, and complexity, the description covers the tool's mechanics (probes, ranks, returns) and provides an example use case. It mentions return fields (score, confidence, signal density) and references the sibling tool ai_visibility_check, making it sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by noting that the first entity in the array is treated as the 'subject' for narrative, and explains the role of entities, models, and context parameters 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 clearly states the tool compares AI visibility across multiple entities, using 'Compare AI visibility across multiple entities side-by-side' and explains it probes each entity with ai_visibility_check and ranks them. It distinguishes from the sibling tool ai_visibility_check by focusing on multi-entity comparison.

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

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

The description provides explicit use cases ('Useful for competitive AI-marketing audits') and example questions, implying when to use. It mentions probing with ai_visibility_check, hinting that single-entity checks should use that sibling tool, but does not explicitly state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds crucial behavioral context: composite fan-out to external services, partial failure handling (sources_failed lists timeouts, rest still returns), and timing detail (bundlephobia first measurement takes 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?

The description is front-loaded with the tool's purpose, but the first sentence is quite long and packed with details. It is informative but slightly verbose. A more concise breakdown would improve readability, but it remains efficient given 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?

The description comprehensively covers the tool's behavior: composite nature, services used, return structure (summary block, advisories, links, alternatives), ecosystem limitation, and partial failure mode. Given no output schema, this provides sufficient context for an agent to understand and invoke the tool correctly.

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

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

Schema description coverage is 100% with both parameters (package and version) documented. The description adds minor context like scoped packages accepted and version defaults to latest, but does not significantly enhance beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, specifying the resources (npm packages) and actions (license, advisories, bundle size) through deps.dev and bundlephobia. It distinguishes itself from sibling tools by naming its specific domain (npm) and composite nature.

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

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

The description explicitly specifies when to use the tool: when an agent asks about safety, popularity, or size of an npm package. It also provides clear exclusion criteria: other ecosystems (PyPI, Maven, Cargo, Go) are handled by a different tool (deps.dev:version directly). This gives excellent guidance for selecting this tool over alternatives.

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

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

Discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flagging, and that returned passages include character offsets and similarity scores. No contradictions with annotations (readOnlyHint, idempotentHint).

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

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

Four sentences, front-loaded with purpose, then usage, then technical details. No redundant information; each 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?

Comprehensive for a search tool: explains what is returned (passages with offsets and scores), constraints (200K chars), and pairing with another tool. Minor omission: no mention of error handling or edge cases like empty text/query.

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

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

Schema description coverage is 100%, and the description adds concrete examples for parameters: 'text' as 'a SEC 10-K body, an article' and 'query' examples like 'supply-chain risk'. This adds meaningful context beyond the schema's generic 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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and explicitly defines the use case (when record is too large for 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?

Provides explicit when to use: 'Use when the record is too big to cram into the prompt.' It also references an alternative (ask_pipeworx_grounded) and explains how the tool's output (offsets) enables verification of verbatim quotes, giving clear context for usage.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: requires OAuth (auth constraint), returns subscription ID, explains delivery channels and their limitations (e.g., SMS 10/day cap, phone verification). 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 a clear lead sentence, followed by requirements, supported types with examples, and delivery channels. It is informative without being overly verbose, though could be slightly more concise by reducing example 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?

Given moderate complexity (3 parameters, nested objects), the description covers return value, prerequisites, all types and delivery options. It lacks details on webhook auto-disable and signing (provided in schema), but is sufficiently complete for an AI agent to understand the tool's 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 descriptions. The top-level description provides additional examples and clarifications for each type (e.g., sec_8k items, polymarket_edge topic) and delivery channels, enhancing understanding 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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses specific verb-resource pairing and distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description implies when to use (when needing a persistent subscription) and includes prerequisites (requires Pipeworx OAuth account, anonymous/BYO cannot persist), but does not explicitly compare with alternatives like recent_alerts for one-time pulls. Lacks explicit when-not-to-use or alternative tool recommendations.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about output format and use case but does not reveal additional behavioral traits beyond what annotations cover.

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

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

The description is relatively long but well-structured, starting with example user queries and then explaining functionality. Each sentence contributes, though it could be slightly more concise without losing meaning.

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

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

Given the simple tool (one optional param, no output schema), the description fully covers purpose, usage, arguments, and output format. It also mentions meta-tools and is complete for an onboarding tool.

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

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

Schema has 100% coverage with param description; the description adds value by explaining the effect of omitting vs. providing the topic parameter and listing example values like 'finance', 'pharma', 'betting', which the schema does not enumerate.

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

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

The description clearly states it returns category-bucketed example questions with exact tool+argument shapes, and positions it as an onboarding entry point. It distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on providing ideas rather than answering questions directly.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains call options (no args vs topic). Lacks explicit when-not-to-use guidance, but the positive guidance is strong and clear.

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

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

Annotations cover read-only, idempotent, non-destructive; description adds the specific fields returned, enriching understanding beyond annotations.

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

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

Two sentences: first defines purpose and output, second gives usage guidance. No redundant information.

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

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

For a simple 1-parameter tool with strong annotations, description fully covers what it does, what it returns, and when to use it.

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

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

Schema coverage is 100% with a clear parameter description; description adds context that task_id comes from a list result, improving usability.

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 retrieves full details of a single Todoist task by id, listing specific fields returned, distinguishing it from list 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 advises use after todoist_list_tasks to inspect one task, providing a clear workflow 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, destructiveHint false. Description adds return field details but no new behavioral traits beyond those inherent in a list operation.

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 efficient sentences with main action first. Every sentence adds value: purpose, definition, return fields, usage suggestion. 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?

Complete for a zero-parameter list tool with good annotations. No output schema but description covers return fields and usage, making it 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?

No parameters; schema coverage is 100%. Description adds value by explaining purpose and return field semantics, earning a baseline 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?

Clearly states it lists personal labels, explains what labels are, and specifies return fields (id, name, color, favorite status). Distinguishes from sibling tools like todoist_list_projects or todoist_list_tasks.

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 use case: 'discover labels for filtering or interpreting task labels.' Could improve by mentioning when not to use or alternatives, but context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by specifying the return fields (id, name, color, etc.), which is especially important since there is no output schema. No contradictions.

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

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

Two sentences: first sentence states purpose and returns, second gives usage guidance. No unnecessary words, perfectly concise and 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 parameterless tool returning a list of projects, the description fully covers what it does, what it returns, and why to use it. Since there is no output schema, the description adequately explains the return values.

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

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

The input schema is empty (0 parameters). Per the rubric, 0 parameters baseline is 4. No additional parameter info is needed.

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

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

The description clearly states the verb 'List', the resource 'projects', and the scope 'in the user's Todoist account'. It also enumerates the returned fields and provides a usage hint, distinguishing it from sibling tools like todoist_list_tasks.

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

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

The description explicitly says 'Use to discover projects and their ids before listing tasks or sections', giving clear guidance on when to use this tool. It does not mention when not to use it, but the context is sufficient for a simple list tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's addition of return fields (id, project id, name, order) adds minimal extra value but is consistent.

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 concise sentences, with the action front-loaded and 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 list tool with one parameter and no output schema, the description adequately explains the purpose, return fields, and 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?

The schema covers 100% of the parameter, but the description enhances it by noting the source of project_id from 'todoist_list_projects', providing helpful context beyond the schema.

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

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

The description clearly states the action (list sections) and resource (within a Todoist project), distinguishing it from sibling tools like todoist_list_projects and todoist_list_tasks.

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

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

The description provides a clear usage context: 'Use to understand how tasks in a project are organized.' It does not explicitly exclude alternatives, but the context is sufficient for a simple tool.

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

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

Annotations already provide readOnlyHint, destructiveHint, and idempotentHint. The description adds that only active/incomplete tasks are listed and specifies the return fields (id, content, etc.), providing useful behavioral context beyond annotations.

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

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

The description is concise (3 sentences) and front-loaded with the main purpose. It efficiently covers filtering and return information without unnecessary words.

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

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

Despite no output schema, the description adequately explains what is returned. It covers filtering options and active-only behavior. It lacks pagination or rate limit info, but annotations (openWorldHint) mitigate the need. Completeness is good for the tool's simplicity.

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

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

Schema coverage is 100% with descriptions. The description enhances parameter semantics by providing example filter queries and noting that project_id comes from todoist_list_projects, adding practical usage guidance 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 'List active (incomplete) tasks / to-do items from Todoist,' specifying the verb and resource. It distinguishes from siblings like todoist_get_task (single task) and other list tools by focusing on active tasks.

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 optional filters by project_id or filter query with examples. It implies when to use (listing tasks), but does not explicitly state when not to use or direct alternatives. However, the context of siblings provides some 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?

Goes beyond annotations (destructiveHint=false) by explaining the row is deactivated, not deleted, and historical events remain. No mention of permissions or rate limits, but sufficient for the action.

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 redundant information. Every word serves a purpose—clear and direct.

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 single-parameter tool with no output schema and annotations present, the description covers purpose, ownership, and behavioral effect. Could mention if undo is possible, but not required.

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 parameter with description 'Subscription id (uuid) returned by subscribe.' Description adds context about ownership enforcement and the effect of cancellation, adding value beyond the schema.

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

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

Description clearly states 'Cancel a subscription by id.' with specific verb and resource, and distinguishes from siblings 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?

Explicitly says ownership is enforced and only own subscriptions can be canceled, and explains the effect as deactivation rather than deletion. Could mention alternatives for permanent deletion, but context from sibling tools is sufficient.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: it uses SEC EDGAR + XBRL, returns a verdict with structured output, actual value with citation, and percent delta. It also notes performance benefits (replaces 4-6 sequential calls). No contradiction.

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

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

The description is well-structured, starting with trigger phrases, then use case, limitations, and output. It is concise but comprehensive, with each sentence providing value. Slightly long but not 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 no output schema, the description fully explains return values (verdict types, actual value, citation, delta). It also notes limitations (v1, company-financial). For a single-parameter tool, it provides complete 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%. The description adds examples of natural-language factual claims, enhancing the schema's description of the 'claim' parameter. It clarifies the expected input format beyond the schema.

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

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

The description clearly states the tool verifies natural-language claims against authoritative sources, specifically for company-financial claims. It provides trigger phrases and examples, distinguishing it from sibling tools like ai_visibility_check or ask_pipeworx.

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

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

The description explicitly says when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims for public US companies). While it doesn't explicitly list when not to use, the domain limitation is clear.

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