Devdocs Io

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

Annotations already indicate read-only and safe behaviour. The description adds important context: the tool uses an external API (Anthropic) with a BYO key model, and that the user incurs costs directly. It also describes the output structure.

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 well-structured sentences that efficiently convey purpose, usage, and output format without unnecessary detail.

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

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

Given the absence of an output schema, the description adequately covers input parameters, output shape, and use cases. It could be more complete with an example output or mention of normalization, but it is still sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the default model for the 'models' parameter and clarifying that '_apiKey' is optional and only needed for Anthropic, but this does not significantly exceed schema documentation.

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 probes LLMs for knowledge about an entity and returns visibility scores per model. It distinguishes itself by specifying the default model and the option to add Anthropic via API key, setting it apart from sibling tools like scan_competitor_ai_presence.

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 checks) and explains when to use the Anthropic option. However, it does not explicitly exclude alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that the tool routes questions to one of 3,547 tools and returns structured answers with citation URIs, providing useful context beyond what annotations offer.

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

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

The description is well-structured with a clear front-loaded instruction, followed by scope and examples. It is slightly verbose with many examples, but each example adds value. 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?

Given the complexity (3,547 tools) and simple schema (just a question), the description is complete: it explains what the tool does, when to use it, provides examples, and mentions the output format (citations). No output schema is provided, so the description compensates well.

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 6 parameters (all aliases for question) with 100% description coverage. The description adds examples of natural language questions and confirms that the input is a question. The examples help clarify usage beyond the schema's descriptions.

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

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

The description clearly states that the tool answers factual questions using structured data from many sources, with explicit instruction to prefer over web search. It distinguishes itself from siblings by listing specific data domains and providing 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 states when to use (for any factual question about real-world entities, events, or numbers) and provides examples. It implies not to use for non-factual queries, and recommends it over web search.

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 idempotentHint=true. The description goes far beyond by detailing resolution logic, classifier fan-out, response shapes, resolver contract, parent event extractor, news fields with fallback mechanisms, safety handling for low-confidence and closed markets, and tradeability 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 lengthy but well-structured with sections on classifiers, fan-out examples, response shapes, and safety. It is front-loaded with purpose and usage. While every sentence adds value, its verbosity slightly reduces conciseness. It could be tighter without losing 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 thoroughly covers all response fields: market_match_confidence, analysis with model probability and edge warning, evidence keys, parent_event, news fields with fallback. It also addresses edge cases like low-confidence resolution, closed markets, and wide spreads. This is highly complete for a complex tool.

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

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

Schema coverage is 100% (3 parameters: market, depth, include_raw). The description adds substantial meaning: for 'market', it explains accepted formats (slug, URL, question text); for 'depth', it defines 'quick' vs 'thorough'; for 'include_raw', it clarifies size implications and use cases. This goes well beyond the schema's own 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies three types of inputs (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_edges or compare_entities by focusing on comprehensive research. The verb 'research' plus resource 'Polymarket bet' is specific and actionable.

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

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

The description explicitly provides usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of when the tool might not work (e.g., closed/de-indexed markets). However, it does not explicitly compare itself to alternatives like polymarket_edges or compare_entities, which would strengthen 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that results are sorted by primary metric, returns paired data with citation URIs, and handles off-calendar fiscal years. 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 somewhat long but front-loaded with key instructions and examples. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

For a tool with only 2 simple parameters and no output schema, the description is very complete. It tells what the output contains (paired data + citation URIs, sorted) and when to use it, covering all context needed.

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

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

Schema coverage is 100% with both parameters described. Description adds significant meaning: for 'type', it details exactly what data is pulled for each enum value; for 'values', it specifies tickers/CIKs for company and drug names, going 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 it compares 2-5 companies or drugs in one parallel call, using verbs like 'compare' and specific examples. It distinguishes itself from sibling tools like entity_profile, which likely handles single entities, by emphasizing parallel 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?

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also specifies data sources for company (SEC EDGAR) and drug (FAERS), helping agents choose correctly.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds only that the database is 'large', which is minor. It does not disclose additional behavioral traits like pagination, rate limits, or data freshness beyond what annotations provide.

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

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

The description is a single short sentence, but it is under-specified. It sacrifices informativeness for brevity, making it less useful than a longer but clearer description.

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 and an output schema, the description should provide at least basic context about what data it returns. It fails to do so, leaving the AI agent without enough information to use the tool correctly.

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

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

The input schema has one parameter 'slug' with 0% description coverage. The description does not explain what 'slug' represents (e.g., document slug, database key). The AI agent receives no semantic help from the description.

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

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

Description 'Content database for a doc (large)' is vague and lacks a verb. It doesn't specify what action the tool performs (e.g., retrieve, query). The name 'db' is generic, and the description fails to distinguish it from sibling tools like search_docs or docs.

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?

No guidance is provided on when to use this tool versus alternatives such as search_docs or docs. The description does not mention any context or exclusions, leaving the AI agent without direction.

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 idempotentHint=true. The description adds behavioral info: returns top-N relevant tools with schemas and examples, 'each result is ready to call directly, no second schema lookup needed'. There is no contradiction with annotations.

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

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

The description is a single efficient paragraph that front-loads the core purpose and enumerates domains compactly. Every sentence adds value—no filler 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?

Despite no output schema, the description fully explains what is returned (top-N tools with names, descriptions, schemas, examples) and how to use it. For a discovery tool, this is complete and sufficient for an agent to understand the 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 description coverage is 100%, so baseline is 3. The description adds value by listing the main parameter 'query' and its aliases (task, q, description, search), mentioning the 'limit' parameter with default/max, and providing two concrete examples ('look up FDA drug approvals', 'analyze housing market trends'). This exceeds simple schema repetition.

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 'Find tools' and the resource 'tools by describing the data or task'. It lists numerous specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes this as a meta-tool for discovering which sibling tool to use, saying 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)'.

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST' for exploring options. It does not explicitly state when not to use it, but the context implies it's for initial discovery, not when the agent already knows the specific 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?

Description adds no behavioral context beyond what annotations already provide (readOnly, openWorld, idempotent, non-destructive). It does not explain what 'full docs index' means in terms of output or scope.

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

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

Extremely short but lacks necessary information. It is not concise in a helpful way; it is under-specified.

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?

Tool has no parameters but output schema exists; description does not explain what the output contains, making it hard for an agent to judge its suitability.

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 exist and schema coverage is 100%, so description need not add parameter info. Baseline 4 applies.

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 'Full docs index' is vague; it does not specify a clear verb+resource. It could mean returning an index or indexing documents, but lacks precision.

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?

No guidance on when to use this tool versus alternatives like search_docs or index. The description fails to provide context on appropriate use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), includes return fields, and flags the patent API soft-failure ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'). 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 example queries. It is fairly detailed (multiple sentences) but each sentence adds value. Some redundancy ('names not supported' appears twice), but overall efficient for the complexity of the tool.

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

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

Despite no output schema, the description thoroughly enumerates return fields (CIK, filings up to 5 with URIs, fundamentals, patents, news, LEI) and explains the patent soft-failure. It covers the key aspects needed for an agent to understand the tool's output, though pagination or limits beyond 'up to 5' are not mentioned.

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 params. The description adds extra context: type enum is restricted to 'company' today, value accepts ticker or zero-padded CIK, and restates that names are not supported (directing to resolve_entity). This goes beyond the schema by explaining the purpose of each value format.

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

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

The description starts with clear example queries ('Tell me about X', 'research Acme'), states the tool provides 'full cross-source profile of a US public company in ONE parallel call', and lists exactly what it returns (CIK, filings, fundamentals, patents, news, LEI). It explicitly distinguishes from chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also specifies that names are not supported and directs to 'use resolve_entity first' in that case, 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 and idempotentHint, so safety is clear. The description adds that output is HTML, but does not disclose behavior for missing entries, response format, or any side effects. With low annotation detail, more context is needed.

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 short (four words), sacrificing clarity for brevity. It lacks structure and fails to front-load critical information like parameter explanations or use cases. Every word must earn its place; this does not.

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 two required parameters and no parameter descriptions, the description is insufficient for an agent to use it correctly. The presence of an output schema is not leveraged. In context of many sibling tools, more completeness is needed.

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 0% parameter description coverage, and the tool description does not explain 'path' or 'slug'. The examples (e.g., 'path: array/map, slug: javascript') offer hints but no explicit semantics, leaving the agent to guess.

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 'Single entry HTML' is vague. It states the output is HTML for a single entry, but does not clarify what 'entry' refers to (e.g., documentation, database record). This lack of specificity hinders the agent's understanding of the tool's purpose.

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

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

No guidance is provided on when to use this tool vs. siblings like 'docs' or 'search_docs'. The agent must infer context from the parameter examples, which is insufficient for confident 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?

Description aligns with annotations (destructive, idempotent) and adds 'clear sensitive data', 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, action front-loaded, 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 use cases, pairing hints, single-param tool with no output schema, annotations 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 100%, description adds no extra meaning beyond schema description 'Memory key to delete'.

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 'Delete', resource 'memory by key', distinguishes from 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Mentions pairing with siblings.

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

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

The description adds context beyond annotations: it explains that it fetches the page, extracts title/description/key links, and outputs a text blob for site-root/llms.txt. Annotations declare read-only and idempotent properties, which match the description. 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 with three sentences, front-loaded with the main action, and no unnecessary words. 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?

Given the simple two-parameter tool and good annotations, the description covers the output format and typical use cases. It could mention error handling for invalid URLs, but overall it's fairly complete.

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

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

Schema coverage is 100%, so description does not need to add much. The tool description does not repeat parameter details, but the schema already provides adequate descriptions. 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 clearly states the tool generates an llms.txt file for AI crawlers, specifying the process (fetches page, extracts metadata) and output format. It distinguishes itself from sibling tools with a unique purpose.

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

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

The description explicitly lists three use cases (client indexing, drafting own project, auditing competitors), providing clear context. It does not explicitly mention when not to use or alternatives, but the usage guidance 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 readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering safety and repeatability. The description adds no additional behavioral context (e.g., pagination, result format), but does not contradict annotations.

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

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

The description is extremely concise (4 words), but this sacrifices clarity. It is front-loaded, yet too minimal to be helpful. Some length would improve understanding without being 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 having an output schema, the description does not describe what the output contains (e.g., list of entries). Annotations are rich, but the overall description fails to give a complete picture for a simple listing 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?

With 0% schema description coverage, the description does not explain the 'slug' parameter beyond the examples. It implies slug identifies a doc, but does not clarify what values are valid or how they are used.

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 'Index of entries inside a doc.' uses a noun phrase without a clear verb, leaving ambiguity about whether it retrieves or creates an index. It does not explicitly state the action, which is crucial for differentiating from siblings like 'search_index' or 'docs'.

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?

No guidance is provided on when to use this tool versus alternatives like 'search_index' or 'entry'. The description lacks context on prerequisites, limitations, or comparison to 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 provide basic read/write hints (readOnlyHint false, etc.), but the description adds critical behavioral details: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. This goes beyond the annotations and helps the agent understand the operational constraints and cost model.

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

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

The description is concise yet comprehensive, using four sentences to cover purpose, usage triggers, audience impact, and constraints. Every sentence serves a purpose, and the most critical information (what the tool does) 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?

Given the tool has 3 parameters (one nested object), no output schema, and moderate complexity, the description fully covers all aspects: parameter usage, rate limits, quota effects, and the fact that feedback is read daily. No missing information that would hinder 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 covers 100% of parameters, but the description adds significant value beyond the schema. For the 'type' enum, it gives concrete examples (e.g., 'bug = something broke or returned wrong data'). For 'message', it advises specificity and length (1-2 sentences, 2000 chars max). The 'context' object is explained but not elaborated 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 is for reporting issues (bug, feature, data_gap, praise) to the Pipeworx team. It explicitly names the verb 'tell' and the resource 'Pipeworx team', and the enum in the schema further clarifies types. Among siblings, no other tool serves a feedback purpose, making it distinctly identifiable.

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: '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 mentions that it's free and doesn't count against quota, which helps the agent decide to use it without hesitation. No alternative tools are listed for similar functions, so no exclusion needed.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), no PII, and caching policy (5min-1h). 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 three sentences, well-structured with bullet points. Every sentence adds value with no redundancy. Could be slightly more concise, but overall efficient.

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

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

Given the tool's simplicity (1 param, no output schema), the description fully covers purpose, usage scenarios, data sourcing, privacy, and caching. 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 single parameter 'window' is fully documented in the schema with enum and description. The description adds a brief note on short vs long window implications, but the schema already covers the meaning. Baseline 3 applies due to high schema coverage.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a window. It defines the resource and verb, but does not explicitly differentiate from sibling tools like 'ask_pipeworx' or 'db'.

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

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

Provides three explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment. Lacks explicit when-not-to-use or alternatives, but the context is clear and actionable.

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 safe read-only, idempotent behavior. Description adds rich behavioral context: walks child markets, checks ordering, computes partition checks, uses Jaccard similarity and placeholder filters. Discloses that response includes opportunities array with specific fields. 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 very verbose and dense with technical details (monotonicity violations, Jaccard similarity, placeholder fractions). While valuable, it could be more structured and concise for easier comprehension by an AI agent. Front-loading the requirement is good.

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, no output schema), the description thoroughly covers behavior and return structure. It explains the response fields (gap_pp, suggested_trade, reasoning, etc.) and technical details like semantic anchor and partition filter.

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

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

Schema descriptions are present (100% coverage), but the tool description adds significant value: explains each parameter's behavior mode, provides example values (e.g., 'fed-decision-may-2026'), and details the processing logic (e.g., walks child markets, computes partition check).

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two modes (event and topic) with specific usage recommendations, 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?

Explicitly requires one of 'event' or 'topic', warns against calling with no args. Recommends 'event' for specific markets and explains when cross-event mode catches patterns missed by single-event. Provides clear guidance on when to use each mode.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint as true, indicating safe, non-destructive behavior. The description goes far beyond this, disclosing caching (1h KV keyed on knobs), response structure (by_segment, diagnostics), edge calculations, model details, and the Fed disclaimer. There is no contradiction with annotations.

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

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

The description is relatively long but well-structured with enumerated model families and clear sections. The first sentence effectively communicates the core purpose. The length is justified by the complexity of the tool. Minor redundancy could be trimmed (e.g., detailed model formulas), but overall it is 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?

Given the absence of an output schema, the description thoroughly explains the response structure (by_segment with three segments, fed_candidates, _diagnostics) and why segments might be empty. It also covers caching and filtering logic. This provides complete context for the agent to understand the tool's behavior and output.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining the purpose and recommended settings for tradeable-edge knobs (min_liquidity, max_spread_pp), the rationale behind min_partition_leg_kelly, and context for slippage_pp. This enhances 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 a clear verb ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price'), specifies the resource (Polymarket markets), and distinguishes it from siblings like polymarket_arbitrage by highlighting the Pipeworx data comparison. The detailed breakdown of model families further clarifies its unique value.

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: 'what should I bet on today' and 'agents discover opportunities without paging hundreds of markets.' It provides guidance on tradeable-edge knobs and filters. However, it lacks explicit instructions on when not to use this tool versus its siblings (e.g., polymarket_arbitrage), which would be helpful for better decision-making.

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

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

Goes beyond annotations (readOnlyHint, openWorldHint) by detailing safety fields like compatibility_warning, temporal_alignment, and skipped_cross_type. Discloses that spreads may be meaningless if temporal alignment is false or if bet shapes are non-equivalent.

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

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

The description is comprehensive but somewhat verbose. It front-loads the core purpose and modes, but includes extensive detail on response fields that could be streamlined. Still effectively structured for clarity.

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

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

Given no output schema, the description thoroughly explains all response fields including leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. Covers edge cases and potential issues, making the tool's behavior fully predictable.

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 value by explaining the two modes and how parameters interact (e.g., using kalshi_event_ticker overrides topic mapping). Provides examples in the schema.

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

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

The description clearly states the tool computes spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic and explicit) and explains the purpose with concrete examples. This distinguishes it from sibling tools like polymarket_arbitrage which are venue-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?

Explicitly guides when to use topic mode vs explicit mode, and warns that most pre-mapped topics return compatibility warnings, indicating actual tradeable spreads are rare. This helps the agent choose appropriately.

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, destructiveHint=false, and idempotentHint=true. The description adds behavioral details: scoping to user identifier, ability to list all keys, and context about prior saving via 'remember'. This adds value 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?

Three sentences, no wasted words, front-loaded with the main action. Every sentence adds information: purpose, usage context, and pairing with other tools.

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 is simple (one optional parameter) and the description covers retrieval, listing, scoping, and pairing. No output schema, but the description adequately explains expected return behavior. 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 schema description coverage is 100% with one parameter. The description adds crucial usage semantics: 'omit the key argument to list all saved keys', which is not in the schema and clarifies 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 description clearly states the tool retrieves a value saved via 'remember' or lists all keys when no key is provided. It uses specific verb-resource pairs ('Retrieve a value', 'list all saved keys') and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description gives explicit context for when to use the tool: 'look up context the agent stored earlier'. It mentions scoping and pairing with remember/forget, but does not explicitly state when not to use or provide alternatives beyond the implied 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 are already clear (read-only, open-world, idempotent, non-destructive), and description adds behavioral context: fans out to multiple sources, fallback logic, soft-fail for USPTO, and return structure.

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 and front-loaded with examples, but slightly long; however every sentence is informative and 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 complexity (multiple data sources, fallback, parameter formats) and no output schema, the description is thorough, mentioning return shape (changes grouped by source, total_changes count, citation URIs).

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 description adds significant value: explains 'since' accepts ISO dates and relative shorthand, lists typical value for monitoring, describes 'value' as ticker or CIK, and confirms 'type' only supports 'company'.

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, with specific examples of queries ("what's new with X", "latest on Y") and distinguishes itself from sibling tool 'entity_profile' which is for static profiles.

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

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

Explicitly mentions when to use this tool vs 'entity_profile', and provides example queries and recommended default values (e.g., '30d' or '1m').

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 valuable context: key-value pair scoped by agent identifier, authenticated vs anonymous persistence (24 hours), and pairing with recall/forget. 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?

Four sentences, front-loaded with purpose, no wasted words. Efficiently covers when, how, and pairing with related tools.

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 write-only tool with 2 fully documented parameters and no output schema, the description is sufficient. It covers persistence behavior and scope, leaving 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 documentation coverage is 100%, so baseline is 3. Description does not add further meaning beyond 'key-value pair' and examples already in schema; it does not explain formatting or constraints on key/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?

Description clearly states the tool saves data for later reuse across conversations/sessions, provides concrete examples (resolved ticker, target address, user preference, research subject), and distinguishes from siblings 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?

Description specifies when to use (discovering something worth carrying forward) and how it pairs with recall and forget. It implies usage boundaries but does not explicitly state when not to use or name specific alternatives among siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it internally cascades through multiple endpoints and performs auto-disambiguation for company inputs, which provides 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 is front-loaded with examples and guidance, and all sentences contribute value. It is slightly verbose but not wasteful; earns a 4 for efficient communication.

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

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

Despite no output schema, the description fully explains return values for both entity types, mentions citations, and notes internal cascading. This is complete 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 coverage is 100% with descriptions for both parameters. The description goes further by detailing the return structure for each type (e.g., ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug), adding significant meaning beyond the schema.

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

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

The description starts with concrete query examples and states the core function: resolving a name to a canonical identifier. It clearly distinguishes itself from siblings like compare_entities by focusing on identifier 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 advises 'Use FIRST whenever you have a name but need an ID,' providing strong usage guidance. It also notes that each call replaces 2-3 manual lookups, implying efficiency. Does not cover when not to use, but the directive is clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds behavioral details: it internally uses ai_visibility_check for each entity, ranks results, and returns score, confidence, signal density. 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 two sentences with a use case and return specification. It is relatively concise and front-loaded with the main action, though the return details could be more structured. No extraneous text.

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

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

Given strong annotations and full schema, the description adequately explains the workflow (probing with another tool, ranking, returning specific fields). No output schema, but returns are described in text. Sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds little beyond schema: it mentions models includes 'workers-ai' default and 'anthropic' requires key, but schema already covers this. Does not significantly augment parameter 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?

Description clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and returns which is most/least recognized. Differentiates from sibling ai_visibility_check by focusing on multi-entity comparison.

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

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

Description explicitly suggests use for competitive AI-marketing audits (e.g., 'does Claude know about us as well as our competitors?'). While it doesn't state when not to use, the context implies it is for multi-entity comparison, leaving single-entity checks to the sibling 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?

Adds significant behavioral context beyond annotations: partial failures via sources_failed, bundlephobia timing, return structure (summary block, per-advisory detail, links, alternative versions). 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?

Dense but each sentence adds information. Could be more structured (e.g., bullets), but appropriate length for the composite nature.

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

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

Covers purpose, usage, return fields, failure modes, limitations. No gaps for agent understanding given 2 params and no output schema.

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

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

Schema coverage is 100%, baseline 3. Description adds value: scoped packages accepted for package, default to latest version for version. Informative but not extensive.

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

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

The description clearly states it is a composite check for npm packages combining deps.dev and bundlephobia. The verb 'scan' and resource 'dependency' are specific. It distinguishes from siblings by noting that other ecosystems fall under deps.dev:version directly.

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

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

Explicitly states when to use: 'is X safe / popular / small' or 'what does adding lodash cost me'. Mentions limitations: NPM only, bundlephobia first measurement can take 5-30s, partial failures degrade gracefully. Lacks explicit when-not-to-use but implies through ecosystem scope.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the specific behavior of substring filtering, but does not discuss pagination, limits, or output details.

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?

A single, concise sentence that efficiently conveys the tool's function without extraneous words. Front-loaded and easy to parse.

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 output schema exists, return values need not be described. Annotations cover safety and idempotence. The core behavior is clear, though finer details like case sensitivity are omitted.

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 0% schema description coverage, the description implies the 'query' parameter is the substring to filter by, but does not explicitly state its role, leaving room for ambiguity.

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 'Filter docs index by substring', clearly indicating the tool searches documents by substring matching. This distinguishes it from siblings like 'search_index' which might search other indices.

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?

No guidance on when to use this tool versus alternatives such as 'search_index' or 'docs'. The description lacks explicit context for 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 already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds 'substring-search' behavior, which is additional 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?

Single sentence, no wasted words. Front-loaded with key action and resource.

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?

Output schema is present, so return values are covered. But parameter semantics are incomplete given low schema coverage. More details on parameters would improve completeness.

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

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

Schema coverage is 0%, so description should explain parameters. However, it only implies 'query' as search term and 'slug' as doc identifier without explicit 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 performs substring-search on entries inside a doc. It identifies the tool as a search function, distinguishing it from sibling tools like search_docs or index, but does not elaborate on 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?

No guidance on when to use this tool versus alternatives. The description only states what it does, not when or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, revealing it as a safe, idempotent read operation. The description adds no behavioral context beyond what annotations already provide, such as pagination, error handling, or query constraints.

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, front-loaded sentence with zero wasted words. It efficiently conveys the core action.

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

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

Although an output schema exists (not shown), the description lacks usage guidelines and parameter semantics, making it incomplete for an agent to reliably invoke the tool. While the tool is simple, the missing details reduce its completeness.

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

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

With 0% schema description coverage, the description must compensate but completely fails to explain the slug parameter's meaning, format, or valid values. It neither adds detail beyond the parameter name nor clarifies how to use it, leaving the agent with no guidance.

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

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

The description 'List categories inside a doc.' clearly states the verb (list), resource (categories), and context (inside a doc). It directly indicates what the tool does and distinguishes from sibling tools, none of which perform a similar function.

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 no guidance on when to use this tool versus alternatives, nor does it specify prerequisites or exclude scenarios. Usage is only implied by the basic action.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. Description adds valuable behavioral details: returns verdict types, structured form, actual value with citation, and percent delta, and states it replaces 4-6 sequential calls. 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 (4-5 sentences), front-loaded with purpose, and every sentence adds value. No redundant or unnecessary text.

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

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

Given the single parameter, high schema coverage, and no output schema, the description is complete. It specifies the domain limitation (v1 supports company-financial claims via SEC EDGAR + XBRL) and describes the return structure sufficiently for an agent.

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

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

Schema coverage is 100% with the 'claim' parameter having a clear description and example. The tool description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Description starts with clear usage phrases like 'Is it true that…' / 'fact check' and explicitly states it is for natural-language claim verification against authoritative sources, with a specific domain of company-financial claims. This distinguishes it well from sibling tools like compare_entities or entity_profile.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the domain. While no explicit 'when not to use' or alternative tools are named, the context of sibling tools and the clear domain limitation provide adequate guidance.

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