Todoist

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining cost implications ('BYO key — you pay Anthropic directly') and default model selection. No contradictions with annotations.

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

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

The description is concise (~4 sentences), front-loaded with the core purpose, and efficiently covers model options, return structure, and use cases. Every sentence earns its place without redundancy.

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

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

Despite no output schema, the description clearly explains the return format per model and combined view. All parameters are covered. Minor gaps: no mention of error handling or rate limits, but overall it's sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100%, yet the description enriches parameter meanings by providing examples (e.g., 'Pipeworx', 'Boston restaurant'), explaining the default model for 'models', and clarifying that '_apiKey' is only needed for Anthropic. This adds significant value beyond schema descriptions.

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

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

The description clearly states the tool's function: probing LLMs for brand knowledge and scoring visibility. It explicitly lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and distinguishes from siblings like 'scan_competitor_ai_presence' by being general rather than competitor-specific.

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

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

Provides clear context for when to use (audits, checks, monitoring) and explains the default model and optional Anthropic key. However, it does not explicitly contrast with similar sibling tools or state when not to use it, missing a score of 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds context that the tool routes questions to specialized tools and returns structured answers with stable pipeworx:// citation URIs. It does not mention any limitations or failure modes, but given the annotations cover safety, the description is sufficiently transparent.

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 reasonably concise and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). It includes examples but could be trimmed slightly without losing clarity. Overall well-structured for an agent.

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 as a router to 3,336 tools, the description covers all essential aspects: purpose, when to use, examples, and output format (structured answers with citations). No output schema exists, so the description adequately explains the return value. The context signals and sibling tools further support this.

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

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

The input schema has 6 parameters with the 'question' parameter described as accepting natural language and multiple aliases. Since schema description coverage is 100%, the description adds little beyond that; however, the description provides examples of questions, which helps illustrate usage. Baseline score of 3 is appropriate.

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

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

The description clearly states that the tool routes factual questions to the appropriate one of 3,336 tools across 747 sources, returning structured answers with citations. It explicitly distinguishes itself from web search and lists numerous domains (SEC filings, FDA data, etc.) and provides concrete examples.

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 preferring this tool over web search for factual queries and provides a list of example questions and query types. It gives strong guidance on when to use it, but does not explicitly state when not to use it (e.g., for creative or subjective questions), leaving a small gap.

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, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral context: fan-out logic per classifier, resolver contract with confidence levels, parent_event extraction, news fallback on GDELT 429, safety measures (low confidence short-circuit, closed market handling), and wide-spread illiquidity warnings. 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 thorough but lengthy (approximately 600+ words). However, it is well-structured with labeled sections (Classifiers, Fan-out, Response Shapes, Resolver, Parent Event, News, Safety) making it easy to scan. Every sentence adds value; no waste. Slight deduction for length but structure compensates.

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

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

Given the tool's complexity (3 parameters, no output schema, but rich annotations), the description covers all necessary aspects: input formats, classifier fan-out logic, response shape fields, resolver contract for matching confidence, parent event extraction for partitioned bets, news error handling, safety closures, and wide-spread warnings. It compensates fully for the lack of output schema.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds further meaning by explaining the market parameter can be slug/URL/question text, depth enum values (quick vs thorough) are expanded, and include_raw rationale is given (keep responses under 20KB vs full payloads). Examples in input schema also clarify usage.

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

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

The description clearly states the tool researches a Polymarket bet using Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet with market-vs-model comparison). It distinguishes from sibling tools like polymarket_edges by being a comprehensive research call, and explicitly lists classifiers and fan-out examples.

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

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

Explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides when-not-to-use: low-confidence matches short-circuit with status, closed markets return blocking status. Implicitly distinguishes from siblings via its comprehensive nature.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: for companies, it explains the data source (SEC EDGAR/XBRL) and a fix for off-calendar fiscal years; for drugs, it lists FAERS, FDA approvals, active trials. Also explains sorting and citation URIs.

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

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

Description is moderately lengthy but well-structured: starts with core purpose, then use cases, then technical details. Each sentence adds value, though a minor simplification could improve conciseness.

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

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

Given no output schema, the description covers return format (paired data, citation URIs) and behavioral details (sorted results, fixed data retrieval). Complete enough for reliable 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% but description adds significant meaning: explains 'type' enum's effect on data sources and 'values' format with examples (tickers/CIKs for company, names for drug). Adds value beyond schema.

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

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

The description clearly states it compares 2-5 companies or drugs side by side, with specific verb 'compare' and resource 'entities'. It distinguishes from siblings by noting it replaces multiple sequential lookups and gives explicit use cases like 'compare X and Y', 'X vs Y'.

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 use cases are provided (compare, vs, which is bigger, rank-by-metric). It differentiates between entity types and their data sources. However, no explicit exclusions or alternatives are mentioned, leaving some ambiguity 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that each result is 'ready to call directly, no second schema lookup needed,' enhancing transparency.

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

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

The description is a single well-structured paragraph that front-loads the purpose, lists example domains, and clearly explains the return value. 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 the absence of an output schema and the number of parameters, the description adequately explains the tool's function and return value. It could mention defaults (e.g., limit default of 20) but is otherwise complete.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds context by summarizing that 'query' accepts natural language and lists aliases, which helps understanding beyond the schema.

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

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

The description starts with 'Find tools by describing the data or task,' which clearly states the tool's purpose. It distinguishes itself from sibling tools by being a discovery and exploration tool, not a specific data retrieval tool.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance. Though it doesn't list when-not-to-use, the instruction 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: return fields (CIK, filings with URIs, fundamentals specifics, patents soft-failure, news fallback, LEI) and internal quirks like the 'Run 6 fix' for FY2025 numbers. No contradiction with annotations.

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

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

The description is fairly long but each sentence adds necessary detail. It is structured with a clear returns list. Minor improvement could be made by condensing some technical notes, but overall it's well-organized and front-loaded.

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

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

Despite no output schema, the description thoroughly explains return fields, including caveats (patents sunset, news fallback, fundamentals timing). For a complex tool with multiple data sources and edge cases, this provides complete context for correct usage.

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

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

Schema coverage is 100%, with both 'type' and 'value' described in the schema. The description adds important nuance: 'type' is only 'company' currently, 'value' accepts ticker or zero-padded CIK, and explicitly states names are not supported. This goes beyond the schema's description.

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

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

The description clearly states 'Get everything about a US public company in one call.' It specifies the tool's purpose and distinguishes it from siblings like 'compare_entities' and 'resolve_entity' by detailing its comprehensive data aggregation role.

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 ('tell me about X', 'research Acme', etc.) and when not to use (names not supported, use 'resolve_entity' first). It also mentions alternatives like calling 10+ pack tools, 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?

The description states 'delete', which is consistent with destructiveHint: true annotation. It adds context about clearing sensitive data, which is useful beyond annotations.

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

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

The description is two sentences, front-loaded with the primary action, followed by usage conditions, and ends with related tools. No unnecessary words.

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

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

For a single-parameter, no-output-schema tool with full annotation coverage, the description is complete: it explains purpose, when to use, and related tools.

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 key is clear. The tool description adds no additional parameter meaning beyond 'by key'.

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 specifies the action (delete), resource (memory), and method (by key). It distinguishes itself from sibling tools 'remember' and 'recall'.

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

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

It provides explicit scenarios for use: stale context, completed task, clearing sensitive data. It does not explicitly state when not to use, but the guidance 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 explains the internal process (fetch, extract title/description/links, emit markdown) and output location hint. Annotations already indicate read-only, idempotent behavior; the description adds useful detail without contradicting annotations. Could mention potential limitations like robots.txt or size limits.

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

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

The description is two sentences: first states the core function and target audience, second lists use cases. It is efficient, front-loaded, 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 the tool's simplicity (2 params, no output schema), the description covers what it does, inputs, and outputs. Missing details about error handling for invalid URLs, but overall adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions max_links default and max but does not add significant meaning beyond the schema. No additional constraints or examples for url parameter are 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 clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and use cases. It distinguishes itself from sibling tools by its unique function, as no other sibling tool generates llms.txt files.

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 (indexing a client's site, drafting own project, auditing competitor). It does not explicitly state when not to use or list alternative tools, but given the narrow scope and lack of similar siblings, the context is clear enough.

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

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

Annotations are neutral (readOnlyHint: false, destructiveHint: false). The description adds behavioral details: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. It implies a write operation but is transparent about limits and impact (team reads digests, signals affect roadmap). 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 concise (5 sentences), front-loaded with the purpose, and well-structured. Every sentence adds value: defining categories, usage tips, and behavioral notes. No unnecessary words or redundancy.

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

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

Given the tool's complexity (3 parameters, one nested object, no output schema), the description fully covers what the agent needs to know: what happens after submission (team reads digests, impacts roadmap), rate limits, and free status. No critical gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add new parameter-level meaning beyond what the schema provides (enum details and nested object descriptions are already in the schema). The description reiterates the enum values but adds context (e.g., rate limits) that is not parameter-specific.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific categories (bug, feature, data_gap, praise) and distinguishes itself from sibling tools by being a feedback channel, not a query or action 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 provides explicit when-to-use guidance: for bugs, feature requests, data gaps, or praise. It offers tips on how to frame feedback (describe in terms of tools/packs, avoid pasting prompts) and mentions rate limits and free usage, helping the agent decide when to use this tool versus 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: it is derived from CF analytics-engine, no PII, returns aggregated counts, and cached 5min-1h. This enhances understanding beyond annotations without contradiction.

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

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

The description is concise (three sentences plus numbered use cases) and front-loaded with the main output. Each sentence adds value, and the structure is easy to parse. No unnecessary words.

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

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

Given the tool's simplicity (one optional parameter, no output schema, rich annotations), the description fully covers what the tool does, what it returns, caching behavior, data source, and use cases. No gaps are apparent.

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

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

Schema coverage is 100% with one parameter ('window') having clear enum values and description. The description adds nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides semantic meaning beyond the raw 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 what the tool does: returns top tools, top packs, and total call volume over a recent window. It specifically mentions the output (top tools, top packs, call volume) and distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on trending signals from other AI agents.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment with agent needs), which helps an agent decide when to use it. However, it does not explicitly mention when not to use the tool or suggest alternatives, leaving room for improvement.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral detail beyond annotations: explains the two modes, partition_check mechanics (sum of YES prices should ≈1, deviations >3pp trigger signals), Jaccard similarity filter (≥0.30), placeholder filter, and response structure. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections for modes, semantic anchors, partition filters, and response. It front-loads the overall purpose and then provides necessary details. Every sentence adds value and justifies its length for a complex tool.

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

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

Given the tool's complexity (two modes, multiple checks, filters, no output schema), the description is thorough. It covers inputs, logic, filters, and response structure. However, it lacks mention of potential errors, limits, or edge cases (e.g., what happens if no opportunities found), which would make it even more 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?

Both parameters have schema descriptions (100% coverage), but the tool description adds significant meaning: for 'event', it specifies it's a Polymarket event slug or full URL with an example; for 'topic', it defines it as a seed question and gives an example. The description also elaborates how each parameter is used in the tool's logic.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic), which differentiates it from sibling tools like polymarket_edges or bet_research. The verb 'find' and resource 'arbitrage opportunities' are specific and unambiguous.

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

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

The description provides explicit guidance on when to use each mode: pass a single event slug for event mode, or a seed question for topic mode. It explains that cross-event mode catches patterns missed by single-event mode. However, it does not explicitly exclude alternatives or compare with sibling tools, so usage context is clear but not fully exhaustive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context, including caching behavior ('Cached 1h at the KV level keyed on all knobs'), details on model families and their edge calculations, and response structure (by_segment, fed_candidates, diagnostics). No contradictions with annotations.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs of dense technical detail. While well-structured with clear segments and front-loaded purpose, it could be more concise for quick agent parsing. Every sentence adds value, but the length may hinder rapid understanding.

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, 3 model families, no output schema), the description is exceptionally thorough. It covers the model families, edge calculation details, tradeable-edge knobs, response structure, caching, and special notes on Fed bets. No gaps remain for agent decision-making.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra context beyond the schema, such as explaining why min_kelly does not filter partitions (requires min_partition_leg_kelly) and detailing the tradeable-edge knobs. This additional semantic value raises the score above baseline.

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

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

The description clearly states the tool scans top Polymarket markets to find opportunities where Pipeworx data disagrees with market price, specifying it's for daily betting discovery. It details three model segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and includes tradeable-edge knobs, making it highly distinct from sibling tools 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 explicitly states the tool is built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It provides clear context for use, but does not explicitly mention when not to use or name alternatives, which would elevate the score to 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral context: return structure (leg-by-leg prices, matches and spreads), safety fields (compatibility_warning with specific conditions like skipped_cross_type and temporal_alignment), and the fact that spreads are meaningless without alignment.

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 thorough but not excessively verbose. It is well-structured: opening purpose, modes, response format, safety fields, and a cautionary note. Each sentence adds value, though some could be slightly shortened without loss of 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 no output schema, the description fully explains the response format (leg prices, spreads, safety fields). It covers both modes, parameter interactions, and edge cases (compatibility_warning, temporal alignment). The tool has moderate complexity with three optional parameters, and the description addresses all necessary contextual information.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the two modes and how explicit parameters override topic mapping. It also provides examples and lists the 10 topic shortcuts, which the schema does not enumerate beyond inline strings.

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: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on two different venues rather than a single one.

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 explains two modes (topic shortcuts and explicit tickers) and provides detailed conditions for meaningful use: bet shapes must be equivalent and temporal alignment must be true. It warns that most pre-mapped topics are not tradeable, offering clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by explaining scoping and memory pattern, 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?

Three sentences, each adding distinct value: function, purpose/examples, scoping/pairing. 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?

Covers core aspects well for a simple tool. Minor gap: does not describe return format (value as string), but examples imply it.

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

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

Schema coverage is 100%. Description reinforces schema by explaining 'omit to list all keys' and giving examples of key values, adding operational context beyond schema.

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

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

Description clearly states retrieval of saved values or listing keys, with examples (ticker, address, notes). Distinguishes from siblings 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 when to use: look up context stored earlier. Mentions pairing with remember/forget and scoping to identifier. Lacks explicit 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?

Discloses fan-out to multiple sources, fallback logic (GDELT→GNews), and soft-failure of USPTO. Describes input format (ISO date or relative shorthand) and output structure (grouped changes, total_changes, citation URIs). Annotations are consistent (readOnlyHint, idempotentHint). 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?

Single dense paragraph flows logically: purpose → use cases → sources → parameter details → output → alternative tool. Every sentence adds value, no redundancy.

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

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

Given the tool's complexity (multiple sources, fallbacks, output structure), the description covers all essential aspects. No output schema, but description explains output format. Includes alternative tool reference.

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

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

Input schema covers 100% of parameters with descriptions. Description adds value with examples for 'since' (e.g., '7d', '30d', '1y') and typical usage recommendation ('Use 30d or 1m for typical monitoring'), enriching 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: monitoring changes for a company over a recent time window, with explicit use cases ('what's happening with X', 'updates on Y'). It distinguishes from the sibling tool entity_profile, which provides static profiles.

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

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

Provides explicit use cases and when-not-to-use: 'Use entity_profile instead for static profile.' Also explains fallback behavior between GDELT and GNews, giving clear context for tool selection.

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 (idempotentHint=true, destructiveHint=false) are consistent. The description adds key behaviors: persistence duration (24 hours for anonymous, persistent for authenticated), scoping by identifier. 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 concise (three sentences) and front-loaded with purpose, then usage, then behaviors. Every sentence adds value; no repetition or fluff. Well-structured for quick parsing.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers all essential context: purpose, usage, scope, persistence, relationships to siblings. No missing information needed for correct invocation.

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

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

Schema coverage is 100% with descriptions for both key and value. The description adds 'scoped by your identifier' but does not provide additional semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies it's a key-value store scoped by agent identifier. Examples (ticker, address, preference) clarify the resource, and mention of sibling tools 'recall' and 'forget' distinguishes it.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete scenarios. Directly references siblings: 'Pair with recall to retrieve later, forget to delete.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds useful behavioral context: internal cascading through several lookup endpoints, replacing 2-3 manual lookups. 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?

Description is well-structured: front-loaded with purpose and primary usage instruction, then details on supported types. Each sentence adds value, though it is slightly wordy but still concise for the information provided.

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, description thoroughly explains what is returned for each type: for company (ticker + CIK + company_name + citation URI), for drug (RxCUI + ingredient + brand + citation). Also mentions internal cascading. 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?

Input schema covers both parameters with 100% description coverage. Description adds extra semantic meaning: auto-disambiguation for company, list of accepted input formats (ticker, CIK, name for company; brand/generic for drug), and examples.

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 resolves a user-spoken name to canonical/official identifiers that other tools require as input, with specific verb and resource. It distinguishes from siblings by highlighting its role as a prerequisite for other 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 instructs 'Use FIRST when you have a name but need an ID.' However, it does not explicitly state when NOT to use it or mention alternative tools, though the context implies it is the primary resolver.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the process: probes each entity, ranks, and returns results. It does not contradict annotations.

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

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

The description is two focused sentences plus an example in parentheses, front-loading the core action and purpose. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description fully explains the return format ('ranked list with score, confidence, signal density per entity'). All 4 parameters are described in the schema, and the description adds usage context. Complete for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds marginal context (e.g., first entry treated as subject) but does not significantly extend beyond schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities, 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) by specifying competitive AI-marketing audits.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an example question. It implies when to use (comparing multiple brand presences) but does not explicitly state when not to use or directly name alternatives, though the context of siblings is available.

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 idempotent and non-destructive. The description adds critical behavioral info: 'Partial failures degrade gracefully — bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out', which is 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 efficient and front-loaded, but it's a single dense paragraph. Adding structure (e.g., bullet points for return fields) would improve readability. Still, every sentence adds value.

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

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

Despite no output schema, the description details the return summary block fields and lists specific attributes. It also covers partial failure behavior. For a tool with 2 parameters, this is exceptionally 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 adequate descriptions for both parameters (package and version). The description adds minimal parameter-specific info beyond what's already in the schema, 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 is a composite check for adding an npm package, specifying verb and resource. It distinguishes from siblings by noting ecosystem scope and fallback to deps.dev for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and states 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by listing the returned fields and implying the operation is non-destructive, without contradicting any 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 extremely concise: two sentences with no redundant words. The first sentence covers functionality and returned fields, the second provides usage guidance. 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 single parameter, no output schema, and the presence of sibling tools, the description is sufficiently complete. It explains what the tool does, what it returns, and how to use it in workflow. 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?

The schema has 100% coverage for task_id with a basic description. The description adds the provenance hint 'from a task list result', which aids understanding but does not provide extensive additional meaning beyond the schema.

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

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

The description clearly states the verb 'Get', the resource 'a single Todoist task / to-do item', and lists the specific fields returned (content, description, project id, etc.). It also distinguishes from sibling tool todoist_list_tasks by suggesting usage after listing.

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 advises 'Use after todoist_list_tasks to inspect one task', providing clear context for when to invoke this tool. It does not mention scenarios to avoid, but the guidance is sufficient for correct usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by detailing what the tool returns (id, name, color, favorite status) and confirms it's a read-only list operation. 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?

Three sentences, each earning its place: what it does, what labels are, what it returns, and when to use. No fluff or redundancy.

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

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

For a parameter-less, read-only list tool, the description is fully complete. It covers purpose, return value, and use case, all aligned with the rich annotations.

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

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

The input schema has no parameters (0), so schema coverage is 100%. The description adds meaning by specifying the return fields (id, name, color, favorite status), which goes beyond the empty 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 uses a specific verb ('List'), noun ('personal labels'), and scope ('in user's Todoist account'). It explains what labels are, clearly differentiating from sibling tools like todoist_list_projects and todoist_list_tasks.

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

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

The description explicitly states the use case: 'Use to discover labels for filtering or interpreting task labels.' While it doesn't list when not to use, the tool's simplicity and lack of siblings in the same domain make this adequate.

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, covering safety and idempotency. The description adds the list of returned fields but does not disclose additional behavioral traits like rate limits or pagination. With strong annotations, the score is adequate.

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

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

The description is two sentences: the first explains what the tool does and what it returns, the second provides usage guidance. It is concise, front-loaded, and contains no unnecessary words.

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

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

For a parameterless tool with no output schema, the description adequately covers functionality, return fields, and usage context. It explains when to use it (before tasks or sections) and what information is returned. 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?

The tool has no parameters, so the schema coverage is 100%. The baseline score for 0 parameters is 4, and the description does not need to add parameter semantics. It correctly omits parameter details.

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

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

The description clearly states it lists all projects in the user's Todoist account, specifying the exact fields returned (id, name, color, etc.). It distinguishes from sibling tools like todoist_list_tasks and todoist_list_sections by focusing on 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 advises using this tool to discover projects and their IDs before listing tasks or sections, providing clear usage context. However, it does not explicitly state when not to use it or mention alternatives beyond the implicit sibling distinction.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining that the tool returns specific fields (id, project_id, name, order) and describes the concept of sections grouping tasks. This complements the annotations with useful behavioral context.

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

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

The description consists of three concise sentences with no fluff. The first sentence states the action, the second explains the grouping concept, and the third lists return fields and usage. Every sentence serves a clear purpose.

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

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

Despite lacking an output schema, the description lists the exact return fields (id, project_id, name, order). It also clarifies the concept of sections and tells where to obtain the required project_id. For a simple list tool, this provides all necessary context.

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

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

The single parameter 'project_id' is fully described in the schema (100% coverage). The tool description adds that this id comes from 'todoist_list_projects', providing a meaningful cross-reference. This extra context enhances understanding beyond the schema alone.

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

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

The description clearly states the verb 'list' and the resource 'sections within a Todoist project'. It explicitly distinguishes from sibling tools like todoist_list_projects and todoist_list_tasks by focusing on sections. The return fields are also specified, making the purpose unambiguous.

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

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

The description provides a usage rationale: 'Use to understand how tasks in a project are organized.' However, it does not mention when not to use this tool or contrast it with alternatives. No explicit exclusion criteria are given, so the guidance is adequate but not comprehensive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, indicating a safe read operation. The description adds that it returns specific fields like id, content, priority, etc., and clarifies it only lists incomplete tasks.

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

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

The description is two sentences, front-loading the main purpose, then covering optionality and return details. No redundant information.

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

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

Without an output schema, the description details the return fields comprehensively. It also explains the filter query with examples. Minor gap: no mention of pagination or limits, but acceptable for a list tool.

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

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

Schema description coverage is 100% with both parameters described. The description adds value by giving concrete examples for the filter query and linking project_id to another tool, enriching 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 from Todoist, distinguishing it from sibling tools like todoist_get_task (single task) and others. It specifies the resource and scope.

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

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

The description provides guidance on optional filters (project id or filter query) with examples, implying when to use them. However, it does not explicitly state when not to use or mention alternatives beyond the implicit sibling distinctions.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds behavioral context: versioning (v1), data source (SEC EDGAR + XBRL), and return format (verdict types, citation style). It does not mention rate limits or authentication, but these are covered by annotations (readOnly implies no side effects).

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

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

The description is two paragraphs, well-structured with purpose, usage, domain, and output details. It is concise yet informative, with no wasted sentences. A slightly more compact formatting could improve readability, but overall effective.

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

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

Given the single parameter, clear annotations, and no output schema, the description fully covers what the agent needs: purpose, when to use, domain, return values (verdict types, citation, delta). No gaps remain for effective tool selection and invocation.

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

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

Schema description coverage is 100%, providing a clear example. The description adds meaning by explaining the type of claims supported (company-financial) and the nature of the parameter (natural-language claim). This enhances the schema definition.

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

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

The description clearly states the tool's function: fact-checking natural-language factual claims against authoritative sources. It specifies the domain (company-financial claims for US public companies) and provides example queries. This distinguishes it from sibling tools like ask_pipeworx or bet_research.

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: when an agent needs to check truth of a user's claim, with example phrasings. It does not provide a when-not-to-use clause, but the domain restriction implies limitations. The replacement of 4-6 sequential calls is a helpful efficiency insight.

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