Todoist

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true. The description adds important behavioral details: default model is free (Workers AI), Anthropic requires BYO key with direct payment, and it returns per-model fields. This goes beyond annotations, though it omits rate limits or failure modes.

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 and front-loaded with the main action. Every sentence serves a purpose: main function, default behavior, optional extension, return format, and use cases. No wasted words despite covering multiple aspects.

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 100% schema coverage, no output schema, and no nested objects, the description provides sufficient context: explains output format, parameter choices, and use cases. It is largely complete but could mention potential cost implications or result variability.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'models', the optional 'context' parameter for disambiguation, and that '_apiKey' is passed through directly. This extra context justifies the higher score.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100). It specifies the verb (probe/score), resource (LLMs, visibility), and scope (business/brand/product/topic). The use cases further clarify intent, and it distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving context on when to use. However, it does not explicitly state when not to use or differentiate from similar sibling tools, which would elevate 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 readOnly/openWorld/idempotent annotations, the description reveals meaningful routing behavior: it selects among thousands of tools, fills arguments automatically, and returns structured answers with citation URIs. This gives the agent an accurate model of what happens at call time without contradicting 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 opening guidance is useful and front-loaded, but the description becomes highly repetitive, repeating the 'START HERE for most questions' block and example list multiple times. The redundant repeated passages waste tokens and obscure the otherwise clear structure.

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 routing tool with no output schema, the description adequately covers scope, supported data domains, trigger phrasing, return shape (structured answer with pipeworx:// citations), and sample questions. It could mention failure/unsupported-query behavior, but the core information an agent needs to invoke it correctly is present.

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

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

The input schema already covers all parameters at 100%: the only real parameter is 'question', with five documented aliases. The description contributes example questions but no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific action ('routes the question to the right one of 5,798 tools') and a concrete outcome ('returns the structured answer with stable pipeworx:// citation URIs'), so an agent can tell this is a general factual-data router. It clearly separates from web search, but it does not explicitly distinguish from the sibling tools ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

It gives explicit trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much') and says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', with concrete examples. It lacks an explicit when-not-to-use statement or named sibling alternatives, though web search is presented as the main alternative.

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

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

Given readOnly, openWorld, idempotent, and non-destructive annotations already cover the safety profile, the description adds valuable non-obvious behavior: it is an experimental edge with live candidate routing, currently no active candidate, results are compared against the stable router, and it has no fallback. This is strong disclosure beyond the structured 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 four sentences are dense but well-organized, front-loading the essential 'beta/identical router' concept before current state and usage. The 2026-07-26 date and 'falls back to nothing' clarification are useful context, so no sentence feels wasted; it is only slightly long.

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 no-output-schema experimental variant, the description gives enough to call it correctly: what it is, current equivalence to ask_pipeworx, usage intent, and the absence of fallback. It relies on the sibling definition for actual response shape and detailed behavior, but that dependency is explicitly disclosed ('same response shape'), making the description complete 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 description coverage is 100%: every parameter is documented as an alias for the required question parameter, which is sufficient semantics. The description does not add parameter-level detail beyond saying the arguments are the same as ask_pipeworx, so baseline 3 is appropriate.

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

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

The description identifies the tool as the beta variant of ask_pipeworx and clarifies it is a universal router with the same 5,798 tools and arguments, which distinguishes it from the stable sibling. It does not define the router's behavior in standalone terms ('ask a question and route it'), leaning on the ask_pipeworx comparison, so it is clear but not maximally self-contained.

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

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

It explicitly tells the agent to use it like ask_pipeworx when the newest/experimental routing is desired, and explains the current no-candidate state makes it behaviorally identical to the stable router. It stops short of explicitly saying 'use ask_pipeworx when you need the stable/production path' and does not mention the grounded sibling, but the alternatives are implied by the comparison.

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 richly discloses behavior beyond annotations: it returns evidence as a verbatim quote, provides a structured refusal object with enumerated refusal reasons, and explains that it never invents facts beyond the tool result. This aligns with and extends the readOnlyHint, openWorldHint, and idempotentHint 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 information-dense but every sentence earns its place: behavior, routing, success and refusal contracts, use cases, and cost trade-off are all covered. It is structured with concrete return shapes and a clear preference rule, and the most important distinguishing trait is front-loaded.

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

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

Even though there is no output schema, the description fully compensates by specifying the exact success and refusal return shapes, the data-source constraint, and the routing mechanism. For a complex tool with a single natural-language parameter, nothing critical is missing.

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

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

The input schema already documents the question parameter fully with aliases and a natural language description, so the description does not need to add much. The description adds context that the question will be routed to other tools, but the schema carries the parameter burden.

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

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

The description states a precise function: a hallucination-resistant answer mode that extracts the answer only from fetched tool results. It explicitly distinguishes itself from ask_pipeworx by naming the sibling and explaining the difference in behavior, so an agent can select it correctly.

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

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

The description gives explicit when-to-use guidance: high-stakes reads where answers will be quoted, cited, or acted on, and where fact-invention is unacceptable. It also gives a when-not-to-use direction: prefer ask_pipeworx for casual lookups, including the cost trade-off.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds extensive behavioral details: fan-out patterns, response shapes, match confidence levels, handling of low-confidence matches, closed markets, illiquid spreads, cancellation rules, and safety checks. This adds significant 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 long but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, safety). Core purpose is front-loaded. However, some repetition and excessive detail (e.g., full fan-out examples) could be trimmed.

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

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

Despite no output schema, the description thoroughly explains response shapes, edge cases (low confidence, closed markets, illiquid spreads), resolution rules, and safety mechanisms. It covers enough context for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100% and the description repeats the schema descriptions for all parameters: market (slug/URL/question), depth (quick/thorough with defaults), include_raw (default false, summary vs raw). No additional meaning beyond schema is provided for parameters.

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, with specific verb 'Research' and resource 'Polymarket bet'. It distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by being comprehensive research covering evidence and market 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 explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not directly mention 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?

The description adds significant context beyond annotations: it details data sources (SEC EDGAR/XBRL, FAERS), correct fiscal year handling, result sorting, and citation URIs. Annotations already indicate read-only, open-world, idempotent, non-destructive, and the description reinforces and enriches these traits.

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

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

The description is a single dense paragraph, but it is front-loaded with the most common usage patterns and uses imperative language. It could be slightly more structured (e.g., bullet points), but it remains concise and informative 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 lacking an output schema, the description fully explains the return format (paired data + URIs), sorting behavior, and what data is pulled per type. Given the tool's simplicity (2 parameters, no nesting), this is complete and leaves no major gaps.

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

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

With 100% schema coverage, the baseline is 3. However, the description adds substantial meaning: it explains what data is pulled for each enum value (e.g., 'company' pulls 10-K metrics) and gives specific examples for the 'values' parameter (tickers/CIKs, drug names). This transitions the enum from a label to a semantic choice.

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 like 'compare' and delineates the scope (2-5 companies or drugs, side-by-side). It explicitly distinguishes itself from sequential lookups and provides example queries. The resource and action are clearly 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?

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and gives example queries. However, it does not explicitly mention when not to use the tool (e.g., for single entities), though this is implied by the sibling tools.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: account and paid-tier requirements, 15-60s/90s latency, parallel tool routing, explicit gaps[] for unanswered facets, a citation_uri only when fetchable, semantic excerpting, and contradictions[] for deeper depths. This fully informs an agent about what will happen.

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 repetitive: 'Decomposes your question...', 'Best for broad/multi-part...', and 'For a single lookup use ask_pipeworx instead' each appear twice, and 'Research workflow.' is a dangling fragment. It opens with an auth caveat before the core purpose, and the exact duplication makes it longer than necessary. Each sentence is informative, but the structure and length are not disciplined.

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

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

With no output schema, the description still tells an agent exactly what to expect: verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and latency. It also covers auth, the alternative tool, and the non-open-web scope. Nothing needed to call or interpret the tool correctly is missing.

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

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

The schema already covers both parameters at 100%, including depth semantics, so the description does not need to redefine them. It adds value by tying depth='thorough' to a paid plan and clarifying how standard/thorough resolve gaps and contradictions and their latency implications. A 4 reflects this useful extra context.

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

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

The description states the action precisely: grounded multi-source research over Pipeworx's structured data sources, decomposing the question into facets and routing them to tools in parallel. It also differentiates the tool by explicitly saying 'this is NOT open-web search' and pointing to ask_pipeworx for single lookups. The purpose is unmistakable despite the duplicate passages.

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 gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx instead'). It also handles the auth edge case by directing unsigned-in users to ask_pipeworx, which works on every tier. This is strong routing behavior.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it returns tools with full schemas and examples, ready to call directly. No contradiction, and it provides useful details beyond annotations.

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

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

The description is well-structured: starts with purpose, lists example domains, describes output, and ends with usage recommendation. It is reasonably concise without missing key information, though slightly 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?

Despite lacking an output schema, the description clearly states what is returned: 'top-N most relevant tools with names, descriptions, and full input schemas.' This is sufficient for a discovery tool. No gaps remain.

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 lists aliases (query, q, task, etc.) and provides examples, but this largely duplicates schema info. It adds minimal new semantic value beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It includes specific examples of searchable domains (SEC filings, financials, etc.) and describes what it returns (top-N relevant tools with schemas). This distinguishes it from siblings as a meta-discovery tool.

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

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

The description explicitly recommends usage: 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context for when to use it, though it 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 declare read-only, idempotent, non-destructive behavior, and the description adds substantial context: parallel fan-out, exact data source domains, `sources_used`/`sources_failed`, fallback behavior (GDELT→GNews), and the rule that an empty section is real 'no data,' not a bug. No contradiction with annotations.

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

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

The description is long, but it is front-loaded with trigger phrases and its most important routing guidance ('ALWAYS PREFER...'). The remainder is dense but mostly necessary given the breadth of sources and edge cases, though it reads as a run-on and could benefit from clearer paragraphing.

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

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

There is no output schema, so the description carries the burden of explaining what the tool returns. It enumerates the major output groups (CIK, filings, fundamentals, patents, contracts, FDA products, hiring, news, LEI), explains `sources_used`/`sources_failed`, and covers failure modes for private companies and unsupported drug types. An agent has enough context to invoke it correctly.

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

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

Schema coverage is 100% and both parameters are richly described in the schema itself, so the baseline is 3. The description adds value beyond the schema by explaining name-resolution behavior, `resolved_from`/`resolved_to` when a name is passed, and the private-company `resolved:false` + `notes` result, which helps the agent anticipate edge cases when selecting the value.

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

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

The description opens with concrete trigger phrases ('Tell me about X', 'research Acme', 'brief me on Tesla') and states a specific verb+resource: a full cross-source profile of a US public company. It clearly differentiates from single-pack SEC/XBRL/news lookups, so an agent can recognize when this is the profile tool rather than a narrower lookup.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives usable input constraints, such as accepting tickers, CIKs, or names, and explains the private-company behavior instead of leaving the agent to discover it through failure.

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 adds context about clearing sensitive data but does not contradict annotations. No significant behavioral insights beyond the structured fields.

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

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

Two sentences: first states purpose, second gives usage guidelines. No redundant words. Every sentence adds value.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, usage guidelines, and related tools. It could mention behavior for non-existent keys but is sufficient for most agents.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The tool description repeats 'by key' but adds no new meaning. Baseline of 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states the action 'Delete a previously stored memory by key' and identifies the specific resource 'memory'. It distinguishes from sibling tools like 'remember' and 'recall' by mentioning them as counterparts.

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 use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', guiding the agent on complementary tools. Lacks explicit when-not-to-use, but 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that it fetches the page, extracts content, and emits standard markdown. This expands on the annotations without contradiction, though it omits error handling or authentication needs.

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, using four sentences to convey purpose, process, and output. It is front-loaded with the key action and provides immediate value without wasted words.

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

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

Given the tool's simplicity (2 params, no output schema, rich annotations), the description is fairly complete. It covers the output format and use cases, but could mention limitations like site accessibility or link extraction depth.

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 reiterates the parameter meanings (URL and max_links with default/max). It adds no significant new semantics beyond the schema, earning the baseline score.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL. It specifies the action, the resource (URL), and the output format. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on the specific llms.txt standard.

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

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

The description explicitly lists use cases: indexing a client's site, drafting for personal projects, or auditing competitors. However, it does not mention when not to use it or alternative tools, leaving some ambiguity.

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. Description adds context on default behavior (active only) and the effect of the include_inactive parameter, going beyond annotations.

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

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

Two concise sentences: first states purpose and return fields, second gives usage guidance. 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?

Adequately covers purpose, return fields, and usage. Missing potential details like pagination or rate limits, but for a simple list tool with good annotations, this is 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% and the description repeats the schema's parameter description. Adds no new meaning beyond what the schema provides, so baseline score of 3.

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

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

Clearly states verb (list) and resource (subscriptions). Differentiates from sibling tools like subscribe and unsubscribe by specifying it returns active subscriptions with detailed fields.

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

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

Explicitly advises when to use: 'before adding more or to find an id to cancel.' Implies alternatives (subscribe/unsubscribe).

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

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

With minimal annotations (all false hints), the description carries full weight. It discloses rate-limiting ('5 per identifier per day'), the claim_token workflow for anonymous follow-up, that the team reads digests daily, that it's free and doesn't count against quota, and that it should not include end-user prompts. This is thorough 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?

Though longer than average, every sentence carries unique value: purpose, when-to-use, exclusions, claim_token mechanics, rate limit, and quota note. The description is front-loaded with the core action and logically structured, with no filler.

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

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

The tool has a nested object param and no output schema, but the description covers all critical operational aspects: feedback types, scope boundaries, parameter semantics, follow-up flow, and limits. It fully equips an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context for claim_token ('Filing without an account returns a claim_token; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed') and guides message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This elevates it above 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback categories (bug, feature/data_gap, praise), distinguishing it from all sibling tools, especially ask_pipeworx, which is for questions rather than 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?

It explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a strong exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with other servers, making the decision boundary unambiguous.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds context: derived from CF analytics-engine, no PII, cached 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?

Two sentences plus bullet points, front-loaded with core function, no wasted words. Every sentence adds value.

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

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

Covers return value (top tools, packs, volume), data source, caching, privacy. Lacks exact output format specification, but given no output schema, it is mostly complete.

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

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

Schema coverage is 100% with a detailed description of the 'window' parameter. The tool description only reiterates window options without adding new semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns top tools, packs, and call volume over recent windows. It uses specific verbs and resources and distinguishes itself from sibling tools like 'discover_tools' 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?

Provides explicit use cases (discovering hot data, confirming canonical choice, aligning use case) and explains when to use different windows. Does not explicitly state when not to use, but context is clear from sibling tools.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral details: monotonicity violations, partition checks, Jaccard similarity threshold (≥0.30), partition filter for placeholders, fill check against CLOB depth, and advice not to trade when realizable_edge_pp ≤ 0. No contradictions.

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

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

The description is front-loaded with the purpose and is dense with technical details, but every sentence adds value. Slightly long due to the complexity, but no wasted words.

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

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

No output schema, but the description thoroughly explains the response structure (opportunities[] with fields, partition_check in event mode, fill_check details). It also references custom sizing via polymarket_fill_risk. Complete for a complex tool with 2 optional parameters.

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

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

Schema description coverage is 100%, and the description enriches each parameter with examples (e.g., event slugs like 'fed-decision-may-2026', seed questions) and explains the algorithmic behavior (walks child markets, searches related events). This adds 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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks', which is a specific verb+resource+method. It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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

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

The description explains when to use each mode: no args for trending scan, `event` for a specific market, and `topic` for cross-event scanning. It recommends `event` for the strongest per-event check and notes that cross-event mode catches patterns single-event misses. No explicit when-not-to-use, but alternatives are covered.

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

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

The description extensively discloses behavioral traits beyond annotations: it explains caching (KV level keyed on knobs, 1h TTL), the structure of results (by_segment, diagnostics), edge computation details (net of slippage, Kelly fractions, 24h move warning), and tradeable-edge filters. Annotations already indicate read-only, open-world, idempotent behavior, and the description adds deep behavioral context without contradiction.

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

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

The description is overly verbose and dense, comprising long paragraphs with many technical details. While it is structured with numbered segments, the length likely exceeds what an agent can efficiently parse. It could be significantly shortened while retaining key information.

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

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

Given the tool's complexity (9 parameters, no output schema, multiple segments), the description is remarkably complete. It details the response structure (by_segment, diagnostics, Fed candidates), explains why segments may be empty, describes each model family's logic, and covers tradeable-edge knobs. The agent can fully understand inputs, outputs, and behavior without needing to infer.

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

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

Schema coverage is 100%, so the schema already adequately describes all 9 parameters. The description adds value by explaining the model families and edge calculations, but it does not focus on individual parameter semantics beyond what's in 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 scans Polymarket markets for edges where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from general market scanning by focusing on disagreements and providing segmented results, but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 the tool is for discovering betting opportunities and mentions it avoids paging hundreds of markets. However, it does not provide explicit guidance on when to use this tool over siblings, nor does it state when not to use it. Usage context is partially conveyed but lacks exclusion criteria or alternative 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 indicate readOnlyHint=true and destructiveHint=false. The description adds critical behavioral context: data is read from snapshots with a 60-day TTL, decay is computed from daily closes (not intraday), and gaps occur when no scan happened. It also details response fields (trend, decay_pp_per_day, lifespan_days, 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 detailed and well-structured, starting with the key question and then explaining response fields. While verbose, every sentence adds value. Could be slightly tightened, but it is effective.

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

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

With no output schema, the description compensates by fully explaining the response format (tracked[], expired[], snapshot_dates[]), including field semantics and edge cases like gaps and TTL limits. The tool has only 2 optional parameters, so completeness is high.

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%, descriptions already cover basics. The description adds context: days lookback default 14, max 30 (with clamp 2-30), window default '1wk' and describes it as 'snapshot family'. This extra detail raises the score above baseline 3.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from 'daily polymarket_edges snapshots', answering 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by focusing on time-series analysis and trend classification.

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 answers when to use it: to assess edge age and decay, differentiating a fresh wide edge from an old one that 'is wide for a reason nobody is willing to take'. It does not explicitly state when not to use or mention alternatives, but the context is clear and informative.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description does not contradict. The description adds behavioral details like walking the ladder, returning slippage, shares filled, verdict, and highlights risks like partial fills and forced directional risk, providing transparency beyond static annotations.

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

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

The description is well-structured with clear sections for single-market vs basket modes, inputs, outputs, and usage guidelines. It is front-loaded with the main purpose. While it is somewhat verbose, every sentence adds necessary detail, making it appropriately sized for the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly explains return values for both modes, including edge cases like thin legs and forced directional risk. It covers all necessary information for an agent to understand the tool's behavior and outputs completely.

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

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

Schema coverage is 100%, so baseline is 3. The description significantly enhances understanding by explaining the side parameter for both modes, size_usd as settlement notional in basket mode, and the dual use of market/event parameters. It adds meaning beyond the schema's basic descriptions.

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

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

The description clearly states the tool is a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on their signals.

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

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

The description explicitly says to use this tool before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the risks of theoretical overround not being capturable and partial basket fills converting arbs into unhedged positions. It requires one of `market` or `event` but could be more explicit about 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 mark the tool read-only and idempotent, and the description adds significant non-obvious behavior: Kalshi fees are not modeled so spreads are gross, unknown legs are never paired, compatibility_codes can be non-empty even with matched pairs, and null temporal_alignment means unknown rather than aligned. This is exactly the kind of disclosure that prevents misinterpretation.

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

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

The description is well-structured with front-loaded definitions and labeled sections, but it is very long and somewhat redundant—for example, compatibility codes are defined and then partially repeated in the per-entry flags explanation. Several explanatory sentences about participant pools and rarity of spreads add context but could be trimmed without losing invocation-critical information.

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

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

Because there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, temporal_alignment, skipped_unclassified, low_confidence_pairs, fees_note, and skipped counters. An agent has enough detail to understand both what the tool returns and how to interpret ambiguous results.

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

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

Schema coverage is 100%, but the description adds real semantic value beyond the property descriptions: `topic` auto-fetches the matching event, explicit parameters enable custom pairings, and both modes run the identical matcher with the same disclosures. It does not need to carry the parameter burden, yet it clarifies cross-parameter behavior.

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

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

The opening sentence clearly identifies the resource and scope: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It is unambiguous and specific, but it is phrased as a noun phrase rather than an action verb, and it does not explicitly distinguish itself from similarly named siblings like polymarket_arbitrage.

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 strong mode-selection guidance: use `topic` for pre-mapped shortcuts or explicit ticker/slug for custom pairings, and warns that pre-mapped topics are not automatically tradeable. However, it never states when an agent should prefer this tool over sibling arbitrage/edge tools, so explicit alternatives and exclusions are missing.

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

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

Annotations already indicate readOnly, idempotent, nondestructive. Description adds that it is scoped to identifier and provides examples of stored data (ticker, address, notes), which is helpful context beyond annotations. 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?

Three sentences: action, examples, scoping/pairing. No unnecessary words; front-loaded with primary action.

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

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

With one optional parameter, no output schema, and good annotations, the description covers retrieval mechanism, scoping, and sibling pairing completely.

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

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

Schema coverage is 100% with a description for 'key'. Description adds that omitting the key lists all keys, which supplements schema. Baseline 3 plus added value justifies a 4.

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

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

Clearly states it retrieves values saved via 'remember' or lists all keys. The verb 'retrieve' with resource 'saved values' is specific, and it distinguishes from siblings like 'remember' and 'forget'.

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

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

Explicitly says to use for looking up context stored earlier, and pairs with remember/forget. However, it does not state when not to use or provide alternatives among siblings, though scoping is mentioned.

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

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

Description states mark_read:true flags events as read, modifying state, which contradicts the readOnlyHint=true annotation. According to rules, contradiction forces a score of 1.

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

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

Description is four sentences (~80 words), front-loaded with main purpose, and every sentence adds value with no redundancy or 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 no output schema, description adequately describes return fields (source, citation_uri, raw payload) and covers all key behaviors (filtering, mark_read, polling). Complete for a simple polling tool.

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

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

Schema coverage is 100% but description adds useful context: type filter example ('sec_8k'), since requires ISO timestamp, mark_read behavior, and limit default of 50. This exceeds baseline of 3 for high-coverage schemas.

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

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

Description clearly states the tool pulls fired events from subscription feed and returns recent alerts with specific fields. This verb+resource combination is distinct from sibling tools like list_subscriptions 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?

Description mentions polling works fine and provides an alternative REST endpoint for scripts/dashboards, giving context on when to use the tool. However, it does not explicitly exclude sibling tools or state when not to use it.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. Description adds details about fallback from GDELT to GNews, soft-fail for patents due to API sunset, and the behavior of the `since` parameter. 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 fairly long but front-loaded with examples. Every sentence adds value, though it could be slightly more concise. No redundancy.

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

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

No output schema exists, but the description explains the return structure: changes[] grouped by source, total_changes count, pipeworx:// citation URIs. This is sufficient for an agent to 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 already provides 100% coverage with descriptions for all parameters. The description adds practical guidance for `since` (ISO date or relative shorthand, recommends '30d'), which is helpful but not essential given 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 provides a change feed for a company, combining SEC filings, news, and patents. It distinguishes itself from the sibling 'entity_profile' tool, which is for static profiles regardless of window.

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

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

Explicitly says when to use this tool vs. 'entity_profile' (use this for recent changes, entity_profile for static profile). Also gives example queries like 'What's new with X' and 'latest on Y', clarifying the use case.

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

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

Annotations provide idempotentHint=true, destructiveHint=false. Description adds that memory is key-value scoped by identifier and explains persistence, going beyond annotations without contradicting them.

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

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

Concise and well-structured: purpose first, then usage, then details. Every sentence adds value without redundancy.

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

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

Given simple parameters and no output schema, description fully covers what the agent needs: what to store, when, pairing with recall/forget, scope, and persistence.

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. Description adds contextual examples (e.g., 'subject_property') and clarifies scope, enhancing but not requiring additional info beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with concrete examples (resolved ticker, target address, user preference). It distinguishes itself from siblings like recall and forget.

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

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

Explicit guidance: 'Use when you discover something worth carrying forward' and pairs with recall/forget. Also details persistence differences for authenticated vs anonymous sessions, helping the agent decide when to use this tool.

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

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

Annotations already signal read-only, idempotent, open-world behavior, and the description adds substantial non-obvious traits: graceful degradation if GLEIF/OpenFIGI is unavailable, ambiguous matches return figi_candidates instead of asserting, unresolved identifiers are explicitly listed, and each call internally cascades through several lookup endpoints. This goes far beyond the annotation defaults.

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 front-loaded with trigger phrases and supported types, and nearly every sentence adds operational value. It could be tightened into more scannable subsections, but the density is justified by the tool's complexity.

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

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

With no output schema, the description compensates by explaining what the tool returns and when: source-labelled identifiers, explicit unresolved fields, figi_candidates for ambiguous securities, and fallback behavior on enrichment outages. It gives an agent enough context to correctly invoke and interpret the tool.

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

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

Although schema coverage is 100%, the description significantly enriches the parameters: it details accepted formats per type, explains ISIN-to-LEI resolution, and warns that bond lookups must pass the issuer exactly as printed rather than the full noun phrase. This is meaning the schema alone does not 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?

The description states a specific verb and resource: it resolves user-spoken entity names to canonical/official identifiers required by other tools. It names the two supported entity types (company, drug), gives concrete example queries, and distinguishes itself from other tools by position as the preliminary identifier lookup step.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID' and provides many natural-language triggers. It does not explicitly name sibling alternatives or when-not-to-use conditions, but the guidance strongly implies the correct selection 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 read-only, idempotent, non-destructive. The description adds value by revealing the internal use of ai_visibility_check, ranking logic, and output fields (score, confidence, signal density per entity). 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 that efficiently convey core function, use case, and output. 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?

For a tool with no output schema, the description adequately explains the return type (ranked list with score, confidence, signal density). Parameters are fully described in the schema. The explanation is complete for an agent to decide when to use and 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% (baseline 3). The description adds extra semantics: the first entity in the 'entities' array is treated as the 'subject' for narrative purposes. This goes beyond the schema description, enhancing understanding.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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?

Provides explicit context: 'Useful for competitive AI-marketing audits' and gives an example question. Does not directly state when not to use or list alternatives, but the usage context is clear and implies comparison with single-entity probes.

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

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

Beyond annotations (readOnly, idempotent), the description discloses potential 5-30s latency for bundlephobia's first measurement and graceful degradation via sources_failed. 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?

Packed with information in a single paragraph, front-loaded with main purpose, every sentence adds value without redundancy.

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

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

Covers composite nature, data sources, return structure (summary block, advisories, links, versions), ecosystem limitation, and partial failure behavior. No output schema needed as description explains return comprehensively.

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

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

Schema coverage is 100%, and the description adds value: 'Scoped packages accepted' for package, and 'Defaults to latest published version when omitted' for version, enhancing understanding beyond schema.

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

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

The description clearly states the composite check purpose, lists data sources (deps.dev, bundlephobia), and specifies the returned information types. It distinguishes from siblings by noting NPM-only scope and referencing alternative tools.

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

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

Explicitly tells when to use (agent asks about safety, popularity, size) and ecosystem scope (NPM only) with clear alternatives for other ecosystems.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. The description amplifies transparency by detailing output format (passages with offsets and similarity scores), embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and the 200K char truncation limit. No contradiction with annotations.

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

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

The description is a single paragraph of ~100 words, front-loaded with the core action. Every sentence adds essential information—purpose, use case, integration, technical details, and constraints. No redundancy or filler.

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 (passages, offsets, similarity scores). It covers input constraints (200K char limit, truncation flag) and algorithmic details. The description is complete for an agent to correctly invoke and interpret results.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by providing examples for the query parameter and reiterating the character limit for text. However, it does not significantly deepen meaning beyond the schema's inline 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: 'Semantic search INSIDE a fetched record.' It identifies a specific verb ('search within') and resource ('text'), and distinguishes itself from siblings by contrasting with fetching whole documents and mentioning integration with ask_pipeworx_grounded.

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

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

The description explicitly guides when to use the tool: 'Use when the record is too big to cram into the prompt.' It explains benefits (saves context, returns only relevant passages) and specifies pairing with ask_pipeworx_grounded. It also notes the character cap and truncation behavior, providing clear usage boundaries.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds significant behavioral context: requires OAuth account, anonymous/BYO cannot persist subscriptions, SMS cap of 10/day, webhook auto-disable after 10 failures. 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 longer but well-structured: main purpose first, then type details, then delivery. Every sentence adds value. Could tighten slightly but remains efficient.

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

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

Given the complexity (multiple types, delivery options, auth), the description covers return value, constraints, and examples fully. No output schema exists, so the description appropriately explains expected 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 coverage is 100%, but the description enriches parameter meaning with concrete examples for each type (sec_8k, polymarket_edge, etc.) and explains delivery channel constraints (phone verification, email pattern, webhook signing secret).

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. It distinguishes 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 provides when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account). It mentions alternative delivery channels and references recent_alerts for pull. However, it does not explicitly exclude use cases like one-time queries.

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. The description adds behavioral context: returns example questions with exact tool+argument shape, draws from live catalog, explains behavior with and without topic argument. 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 verbose (over 100 words) with multiple alternate phrasings and a long list of categories. While well-structured (user questions, function, arguments), it could be more concise.

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

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

For a tool with 1 optional param and no output schema, the description is highly complete. It explains purpose, output structure (category-bucketed with exact tool+argument), when to use, and argument behavior. No gaps remain.

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 terse description for the 'topic' parameter. The description adds meaningful semantics: lists example values (finance, pharma, etc.), explains default behavior (full spread), and says it's optional. This is beyond the schema's minimal description.

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

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

The description clearly states the tool as an onboarding entry point that returns category-bucketed example questions. It distinguishes from siblings like ask_pipeworx and discover_tools by explicitly recommending it 'FIRST when you do not yet know what Pipeworx can do'.

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 it (first connection, unknown capability, learning meta-tools) and provides example queries. It lacks explicit when-not statements 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 declare readOnlyHint, idempotentHint, and non-destructiveHint, so the description doesn't need to reiterate safety. It adds value by enumerating the returned fields, which gives the agent a clear picture of the output without needing to call the tool. 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?

Two concise sentences with no unnecessary words. The first sentence specifies purpose and output fields; the second provides usage instruction. Every sentence earns its place.

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

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

Given the tool has one parameter, full annotations, and no output schema, the description covers all needed information: what it does, when to use it, what parameters are required, and what fields are returned. No gaps.

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

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

The input schema covers the single parameter with description, and the description adds context that the id comes from a task list result, aiding correct invocation. With 100% schema coverage and extra guidance, the description fully compensates.

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

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

The description clearly identifies the verb 'Get' and the resource 'Todoist task', lists specific fields returned (content, description, project id, etc.), and distinguishes from sibling tool todoist_list_tasks by stating it retrieves a single task's full details.

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 'Use after todoist_list_tasks to inspect one task,' providing clear context on when to employ this tool versus alternatives, and implying it requires a prior list operation to obtain the task_id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns id, name, color, favorite status, which is useful but not beyond what annotations convey. No additional behavioral traits disclosed.

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

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

Three concise sentences: action, explanation, and use case with return fields. No redundant information, efficient and clear.

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

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

Completely adequate given zero parameters and no output schema. The description fully informs the agent about the tool's result and purpose.

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 100%), so baseline is 4. Description adds value by specifying the returned fields (id, name, color, favorite status), compensating for the lack of parameters.

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

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

States 'List all personal labels in the user's Todoist account' with a specific verb and resource, clearly distinguishing it 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?

Explicitly says 'Use to discover labels for filtering or interpreting task labels', providing a clear use case. Lacks explicit when-not-to-use or alternative tools, but implied context 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 declare read-only and non-destructive. Description adds valuable behavioral context: returns specific fields and purpose. No contradiction.

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

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

Two sentences, front-loaded with key action, no filler. Every sentence earns its place.

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

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

For a parameterless tool with no output schema, description fully covers purpose, return fields, and usage context. No gaps.

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

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

No parameters. Schema coverage is 100%. Description does not add parameter-level detail, but none is needed. Baseline 4 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?

Clear verb 'list' and resource 'projects'. Specifies returned fields. Distinguishes from siblings by stating it's a prerequisite for listing tasks/sections.

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 use case: 'discover projects and their ids before listing tasks or sections.' Provides clear context, though does not explicitly mention when not to use.

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

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

Annotations already convey readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying the exact fields returned (id, project_id, name, order) and clarifying it lists sections within a project, which aligns 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 three sentences with no wasted words. It front-loads the core action and purpose, then details the return fields. Every sentence adds value.

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

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

For a simple read-only tool with one parameter and strong annotations, the description sufficiently covers what the tool does and what it returns. It does not need to explain return values since the description already does so.

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

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

Schema coverage is 100%, and the schema description for project_id is clear. The description does not add additional parameter meaning beyond what the schema provides, but it does explain the output structure, which indirectly aids understanding.

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

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

The description clearly states the action ('List the sections'), the resource ('within a Todoist project'), and the purpose ('understand how tasks in a project are organized'). It distinguishes from sibling tools like todoist_list_tasks and todoist_list_projects by focusing specifically on sections.

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

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

The description provides context for when to use the tool ('Use to understand how tasks in a project are organized'). It implicitly suggests needing a project_id from todoist_list_projects, but does not explicitly state when not to use it or name 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, idempotentHint, and non-destructive behavior. The description adds value by detailing return fields and filter syntax, 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?

Two well-structured sentences: first states purpose, second adds details. Every sentence earns its place with no wasted words.

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

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

Given no output schema, the description sufficiently explains return values. With adequate annotations and two optional parameters, it covers all necessary context 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?

Schema coverage is 100%, and the description adds meaningful examples and explains the filter query language, providing additional 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 it lists active (incomplete) tasks with optional filters, using a specific verb and resource. It distinguishes from siblings like todoist_get_task and todoist_list_projects.

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

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

The description provides clear context on when to use (listing tasks with optional filters) but does not explicitly state when not to use or suggest alternatives. The sibling tool list provides implicit differentiation.

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

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

Discloses key behavioral traits beyond annotations: ownership enforcement, row deactivation (not deletion), and historical event preservation. No contradiction with annotations (idempotentHint=true 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?

Two sentences, front-loaded with key action and constraints. Every sentence provides unique value, no redundancy.

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

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

Covers core behavior, ownership, and side effects. No output schema needed. Could mention error handling for invalid/non-owned IDs, but annotations (idempotent, openWorld) reduce need.

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

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

Schema coverage is 100% with one parameter described as 'Subscription id (uuid) returned by subscribe.' Description merely restates 'by id' without adding new semantics, meeting baseline for full coverage.

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

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

Clear verb 'Cancel' targeting a subscription by id, with ownership enforcement and deactivation semantics. Distinguishes from siblings like 'subscribe' by specifying cancellation.

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

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

States ownership constraint and non-destructive nature, implying when to use (cancel own subscriptions) and that historical alerts remain accessible. Lacks explicit alternatives or when-not-to-use, 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 declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds critical behavioral context: the meaning of 'could_not_verify' (verification_error, NOT evidence for/against), the distinction from 'unsupported', and the return of a verdict with citation and reasoning. This is significant added 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 long but well-structured and front-loaded with trigger examples. Each section (usage, routing, return values, caveat, replacement value) carries necessary information. The trigger phrase list is slightly redundant but serves to disambiguate natural-language inputs. No wasted sentences.

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

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

With no output schema, the description explains the verdict types, evidence citation, reasoning, and the verification_error field. It covers both financial and non-financial paths, plus the important could_not_verify vs. unsupported distinction. Given the tool's complexity and 2-param schema, the description is fully sufficient for an agent to understand behavior and output.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much beyond the schema for 'claim' or 'tolerance_pct'; it mentions tolerance in passing ('exact percent-delta math') but relies on the schema's detailed parameter descriptions. No extra semantic enrichment is provided.

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

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

The description begins with natural-language trigger phrases and clearly states 'natural-language claim verification against authoritative sources.' It specifies the exact resources (SEC EDGAR + XBRL for company-financial claims, grounded pipeline for others) and distinguishes itself from siblings by noting it replaces 4–6 sequential calls. This is a specific verb+resource with strong sibling 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates usage by claim type (company-financial vs. any other) and describes the routing. It does not explicitly name alternative tools or describe when NOT to use this tool, but the guidance is clear enough for correct selection.

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