Ncbi Eutils

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds behavioral context: it routes to 1,423+ tools, fills arguments, returns structured answers with stable citation URIs. This is more than the annotations provide, though it could mention potential response time or failure modes.

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

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

The description is moderately long but each sentence adds value. It is front-loaded with the key directive ('PREFER OVER WEB SEARCH') and organized with domain list, mechanism, trigger phrases, and examples. A slight reduction in domain enumeration could improve conciseness without losing completeness.

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, no output schema, but high schema coverage, the description covers all necessary context for an agent: what the tool does, when to use it, how it works (routing to internal tools), and what the output looks like (structured answer with citations). The examples further clarify scope.

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

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

Only one parameter ('question') with 100% schema description coverage. The description greatly enriches the parameter's semantics by specifying the types of questions, criteria for use, and providing examples. This goes well beyond the simple schema description of 'Your question or request in natural language'.

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

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

The description explicitly states the tool's purpose as a factual Q&A router for authoritative structured data, listing many domains and distinguishing itself from web search. It clearly differentiates from sibling tools like efetch and esearch by positioning itself as a broad query router rather than a specific data fetcher.

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 strong usage guidance: 'PREFER OVER WEB SEARCH' for specific data categories, lists query patterns ('what is', 'look up', 'find'), and gives concrete examples. It lacks explicit exclusion cases or direct comparisons to individual siblings, but the context is clear enough for an agent to decide when to invoke.

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

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

Beyond annotations (readOnly, openWorld, non-destructive), the description discloses key behavioral traits: resolves the market, classifies bet type, fans out to relevant packs (e.g., crypto+fred+gdelt for BTC), returns evidence packet and market-vs-model comparison. Also explains depth parameter behavior (quick vs thorough). No contradiction with annotations.

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

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

The description is a single paragraph of about 5 sentences. It front-loads the core purpose, then details behavior and use cases. Every sentence adds value, though slightly verbose in listing examples. Overall efficient and well-organized.

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 data sources, classification, evidence packet) and lack of output schema, the description adequately explains the workflow and output (evidence packet + model comparison). It does not detail output format, but the description covers the essential behavioral path for an agent to understand what the tool does and expects.

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 (market, depth) have descriptions in the schema (100% coverage). The description adds practical meaning: explains that market can be a slug, URL, or question text; depth defaults to thorough and quick uses 2-3 sources while thorough does full fan-out. This provides real-world context beyond the enum and string 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 Pipeworx data. It specifies the action (research), resource (Polymarket bet), and method (pulling Pipeworx data). It distinguishes from sibling tools by noting it's a core demo product that automates fan-out to data packs, unlike other tools that require manual discovery.

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

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

The description explicitly lists use cases: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It implies context for use but does not explicitly state when not to use it or name alternatives, though the sibling list includes other data retrieval tools. The last sentence about agents that use this tool converting better suggests preference over manual pack discovery.

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 readOnly, openWorld, non-destructive. Description adds return format (paired data, citation URIs) and data sources (SEC EDGAR, FAERS). No contradictions; supplements annotations well.

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 main purpose. Each sentence adds value: purpose, trigger phrases, type-specific data, efficiency claim. No fluff.

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

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

Covers both entity types, data sources, return format. No output schema, but description compensates by stating what data is returned. Minor gap: could mention max items (5) explicitly, but schema covers that.

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%. Description reinforces with examples for 'values' (tickers/CIKs for company, drug names for drug) but adds little beyond schema. Adequate but not enriched.

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

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

Clearly states it compares 2-5 companies or drugs side by side, with specific data sources. Differentiates from siblings like entity_profile by focusing on comparison and efficiency (replaces 8-15 calls).

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

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

Provides explicit usage scenarios: user phrases like 'compare X and Y', 'X vs Y', etc. Specifies two types with data sources. Lacks explicit exclusion criteria (e.g., when to use entity_profile instead).

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns top-N most relevant tools with names+descriptions, which is consistent and sufficient.

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 (a few sentences) and front-loaded with the purpose. It efficiently conveys the tool's role without unnecessary details.

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 (no output schema, two parameters), the description is complete. It covers purpose, usage, parameters, and provides examples.

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

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

Schema coverage is 100% with both parameters described. The description supplements by explaining the query parameter as natural language and providing example queries, adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It gives extensive examples and distinguishes it from sibling tools by emphasizing its role as a discovery tool.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use the 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, destructiveHint=false, and openWorldHint=true, covering safety and side-effect behavior. The description adds that it returns text based on rettype, which is consistent. No disclosure of additional behavioral traits like rate limits or error handling.

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 one short sentence that concisely conveys the core purpose and output format. It is front-loaded with key information 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?

Given the complexity of 4 parameters (2 required) and no output schema, the description is minimal. It does not explain required parameters (db, ids), mention error behavior, or provide context relative to sibling tools. Annotations cover safety but not operational details.

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

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

Schema description coverage is 50% with retmode and rettype having descriptions. The description clarifies that rettype controls output format (e.g., FASTA, GenBank), adding value. However, required parameters db and ids lack explanation, and the description does not fully compensate for the 50% coverage gap.

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 returns full records in various formats (XML, GenBank, FASTA) per rettype. The phrase 'Full records' contrasts with summary tools like esummary, but it does not explicitly differentiate from other sibling tools.

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

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

No guidance is provided on when to use efetch versus alternatives like esearch, esummary, or elink. The description only states what the tool does without contextual usage cues.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it queries all databases, which is helpful but does not disclose behavioral traits like result format, pagination, or rate limits. It provides minimal extra context beyond the annotations.

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

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

The description is a single sentence, extremely concise and front-loaded. It earns its place, but could be slightly improved by adding a brief note about the parameter.

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

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

For a simple tool with one parameter, no output schema, and annotations present, the description is nearly complete in describing the tool's high-level purpose. However, the missing parameter documentation leaves a significant gap, making it insufficient 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?

There is one parameter 'term' with 0% schema coverage (no description in input schema). The description does not mention or explain this parameter at all. The agent receives no guidance on what value to provide (e.g., search syntax, format), making it highly ambiguous. This does not compensate for the poor 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 'Global query across all Entrez databases' clearly states it queries all Entrez databases, which is a specific verb+resource. It hints at a cross-database search, distinguishing it from siblings like esearch (single database) and efetch (fetching records). However, it could be more explicit about the query 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 is provided on when to use this tool versus alternatives like esearch, efetch, or elink. There is no mention of context or exclusions, leaving the agent to infer usage from the name alone.

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 (readOnlyHint=true, openWorldHint=true) already provide. No mention of rate limits, return format, or 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?

Extremely concise (4 words) and front-loaded. However, it may be too terse for clarity, earning a 4 rather than 5.

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 optional parameter, no output schema), the description is adequate but could mention what kind of info is returned (e.g., field names, counts).

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 rephrases the parameter's purpose ('Optional db name; omit for global db list') without adding new semantic meaning.

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 'Database info / field list' clearly states the tool's purpose as providing database information or listing fields. It is specific to info retrieval but does not strongly differentiate from sibling tools like esummary or eparams, though the context implies it's for database metadata.

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 explicit guidance on when to use this tool versus alternatives like esearch or efetch. The description is too brief to indicate preferred use cases or prerequisites.

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 the tool is read-only and non-destructive. The description adds no behavioral context beyond this, such as potential rate limits, required authentication, or side effects of linking. It does not contradict annotations, but fails to provide additional 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 extremely concise (three words), but it sacrifices clarity and completeness. It is under-specified and does not earn its place as a useful guide for the 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 has 4 parameters (3 required), no output schema, and low schema documentation, the description provides almost no context. It fails to explain the linking process, the databases involved, or how to construct a valid request. The description is severely incomplete.

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 only 25% (only 'linkname' has a description). The tool description does not explain any parameters, leaving the agent to infer the meaning of 'dbfrom', 'dbto', 'ids', and 'linkname' from their names alone. This is insufficient.

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

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

The description states the tool 'Links across databases,' which indicates a specific action (linking) and a resource (databases). However, it lacks specificity about the nature of the linking (e.g., finding related records) and does not differentiate well from sibling tools like 'efetch' or 'esearch' that also operate across databases.

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 'esearch' or 'efetch.' There are no examples, prerequisites, or context to help an agent decide the appropriate 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 mark readOnlyHint true and destructiveHint false, so safety is clear. The description adds value by disclosing the exact data returned and that responses include pipeworx:// citation URIs, but could mention potential rate limits or pagination.

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 lean 3 sentences covering purpose, usage, and output—no wasted words. Critical information is front-loaded, making it efficient for AI 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?

Despite no output schema, the description enumerates all major return categories (filings, fundamentals, patents, news, LEI), which is sufficient for an agent to understand and invoke the tool correctly given the annotations and 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 both parameters. The description enriches this by clarifying the type enum (only 'company' supported) and adding that value supports ticker or CIK but not names, directing users to resolve_entity when needed.

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

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

The description opens with 'Get everything about a company in one call,' a clear verb+resource statement that immediately conveys the tool's purpose. It lists specific data types (SEC filings, fundamentals, patents, news, LEI) and contrasts with sibling tools like resolve_entity, ensuring distinctiveness.

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

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

Provides explicit when-to-use examples matching user intents (e.g., 'tell me about X', 'research Microsoft') and advises when to use resolve_entity instead for name lookups. The phrase 'otherwise need to call 10+ pack tools' gives clear context for opting for 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?

The description is consistent with annotations (readOnlyHint=true, destructiveHint=false) but adds no behavioral context beyond what annotations provide. No mention of pagination or specific database behavior, but 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 a single sentence, which is concise but too minimal. It front-loads the purpose, but lacks structure and additional context that could improve 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 5 parameters, no output schema, and siblings like efetch/elink, the description does not explain how esearch fits into workflows (e.g., returning UIDs for subsequent fetching) or how pagination works. Incomplete for effective tool 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 description coverage is 40% (only sort and retmax have descriptions). The description does not explain the purpose of required parameters 'db' and 'term'. It fails to compensate for the low 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 states 'Search a database → uid list,' clearly indicating the action (search) and outcome (list of UIDs). It distinguishes from siblings like efetch and esummary that retrieve details, but 'database' is vague without context from annotations (openWorldHint).

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 explicit guidance on when to use this tool versus alternatives such as efetch or egquery. The description does not mention typical workflows (e.g., search first then fetch) 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 indicate readOnlyHint=true and destructiveHint=false. The description adds no behavioral details beyond stating 'summary records', failing to describe what the summary contains or any 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 excessively concise (4 words). While front-loaded, it sacrifices clarity for brevity, resulting in under-specification.

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 and low parameter coverage, the description should explain what 'summary records' entail, cite examples, or clarify scope. It fails to provide sufficient context 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 description coverage is 0%. The description only mentions 'by uid', hinting at the ids parameter, but completely ignores db and retstart. No parameter descriptions exist in schema or 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 states it summarizes records by uid, but the verb 'summary' is ambiguous and doesn't specify the resource type or database. It provides a basic idea but lacks specificity.

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 siblings like efetch or esearch. No context about prerequisites 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?

Description aligns with annotations (destructiveHint=true, readOnlyHint=false) and adds context about clearing sensitive data, which goes beyond annotation alone.

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

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

Two sentences, no wasted words, front-loaded with the action. Every sentence adds value.

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

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

For a simple delete tool with one parameter, the description covers purpose, usage, and behavioral context. Missing return value info but acceptable given triviality.

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 'key' parameter already described. Description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states 'Delete a previously stored memory by key,' providing a specific verb and resource. It distinguishes itself from siblings like '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 lists three scenarios for use (stale context, task done, clear sensitive data) and suggests pairing with remember/recall. Does not explicitly state when not to use, but provides sufficient guidance.

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

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

Annotations are minimal (readOnlyHint, destructiveHint, openWorldHint all false). The description adds valuable behavioral info: rate limit of 5 per identifier per day, free usage, and that it doesn't consume tool-call quota. 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 a single paragraph that efficiently covers purpose, usage conditions, content guidance, and rate limits. It is front-loaded but could be slightly more concise without losing 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?

For a simple feedback tool with no output schema, the description covers all necessary aspects: what it does, when to use it, how to formulate feedback, and operational constraints. No gaps.

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

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

Schema coverage is 100% and parameter descriptions are already detailed, especially for the 'type' enum. However, the description adds extra guidance on message content (describe in terms of tools/packs, avoid pasting prompts), which is not 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 is for providing feedback to the Pipeworx team about bugs, missing features, data gaps, or praise. It distinguishes from sibling tools like ask_pipeworx (for asking) and discover_tools (for discovery).

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

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

The description explicitly specifies when to use each feedback type (bug, feature/data_gap, praise) and what not to include (end-user prompts). It also notes rate limits and that the tool is free and doesn't count against quota.

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 valuable behavioral context: it explains the underlying logic (monotonicity checking), the search process across events, and the return format (ranked opportunities with reasoning). 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 coherent block that front-loads the purpose, then details modes and examples. It is reasonably concise, though the middle section on cross-event mode is slightly verbose and could be tightened.

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 read-only analysis tool with no output schema, the description adequately covers behavior, inputs, and outputs (ranked opportunities with direction and reasoning). It does not explain all edge cases or expected behavior when no opportunities exist, but overall it is complete enough for the 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 basic parameter descriptions. The description adds significant meaning by detailing the two modes, providing usage context and examples (e.g., 'when-will-bitcoin-hit-150k' and 'Strait of Hormuz traffic returns to normal'), which goes beyond what the schema offers.

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 by checking monotonicity violations, and explains two distinct modes ('event' and 'topic'). This specific verb+resource pairing, along with mode differentiation, makes the purpose unmistakable and distinguishes it from siblings.

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

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

The description provides explicit guidance on when to use each mode (single-event vs cross-event) and explains why cross-event mode catches cases single-event misses. However, it does not compare this tool to sibling tools like 'polymarket_edges', nor does it explicitly state when not to use it, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds rich behavioral context: it uses a lognormal model from FRED and live coinpaprika price, groups by asset, fetches price history once, and ranks by |edge|. There is no contradiction with annotations, and it fully explains the internal logic.

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

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

The description is moderately concise with front-loaded purpose. It contains no filler, but a few technical phrases (e.g., 'lognormal model from FRED + live coinpaprika price') could be simplified. Overall it is well-structured and 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?

Despite lacking an output schema, the description fully covers what the tool returns (top N ranked by edge magnitude with suggested trade direction) and explains the algorithm. Given the tool's complexity and zero required parameters, the description is sufficiently complete.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by stating defaults for limit (10) and window ('1wk'), and contextualizes the window parameter as 'Polymarket volume window'. It doesn't reiterate all schema details but provides useful defaults and 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 scans high-volume Polymarket markets, identifies where Pipeworx data disagrees with market price, and returns top N opportunities ranked by edge magnitude. It uses specific verbs ('scan', 'return', 'rank') and explicitly distinguishes itself from siblings like polymarket_arbitrage by focusing on opportunity discovery rather than 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 frames the tool for the 'what should I bet on today' question and states it saves agents from paging through markets. It mentions the V1 scope (crypto-price bets) but does not explicitly exclude other contexts or name alternatives. Still, it provides clear guidance on its intended use case.

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

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

Discloses scoping (anonymous IP, BYO key hash, or account ID) and listing behavior beyond annotations. Annotations show readOnlyHint=true and destructiveHint=false, and description adds useful behavioral details 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?

Two well-structured sentences, front-loaded with purpose, and no redundant information. Every sentence serves a clear function.

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

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

Given simple schema with one optional parameter and no output schema, the description is complete enough. It covers purpose, usage, scope, 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 already covers the single parameter with 100% description coverage. The description adds a bit by explaining the effect of omitting the key, but does not significantly add beyond what's 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 retrieves a value saved via 'remember' or lists all keys when the argument is omitted. It distinguishes from siblings 'remember' and 'forget' by describing the complementary action.

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 context for when to use: to look up stored context without re-deriving. Mentions scoping and pairing with remember/forget, but lacks explicit conditions for when not to use or detailed alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavior: fanning out to multiple sources in parallel, return structure (structured changes + count + URIs), and supported date formats. No contradictions with annotations.

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

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

The description is a single paragraph of about 80 words, front-loading the purpose and followed by examples, behavior, and return format. Every sentence provides value; no unnecessary words or repetition.

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

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

The description covers the main purpose, source fan-out, parameter formats, and return structure. Given the tool's complexity, it is nearly complete. Minor gaps: no mention of pagination or error handling, but annotations' openWorldHint suggests flexibility.

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 adds valuable details beyond schema: clarifies 'since' format (ISO or relative shorthand with examples), recommends default values, and explains 'value' with examples. It also confirms the only supported type is '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 the tool retrieves recent changes about a company from multiple sources, provides example queries like 'what's happening with X?', and lists the sources (SEC EDGAR, GDELT, USPTO). This makes it distinct from sibling tools such as entity_profile or compare_entities.

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 includes explicit example queries and contexts for when to use the tool (e.g., monitoring changes, 'brief me on what happened'). However, it does not explicitly state when not to use it or compare it to alternatives, which would make it even stronger.

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 storage mechanism (key-value scoped by identifier), persistence details (authenticated persistent, anonymous 24h), and pairing with other tools. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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?

Five sentences, no fluff, each sentence serves a purpose. Front-loaded with main action and 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?

Given the simple tool (2 parameters, no output schema), the description covers purpose, usage, behavior, and sibling relationships fully.

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 3. Description adds context: provides example keys and explains value as any text. Slightly exceeds 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 verb (save) and resource (data for reuse), distinguishes from siblings (recall, forget). It provides specific use cases like resolved ticker, target address, user preference.

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

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

Explicitly advises when to use: 'when you discover something worth carrying forward'. Mentions alternatives: 'Pair with recall to retrieve later, forget to delete.' Also covers persistence scope differences.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so description adds value by specifying return includes IDs and citation URIs, and mentions the types of identifiers (CIK, ticker, RxCUI, LEI).

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 a single paragraph that is front-loaded with main purpose, uses clear examples, and every sentence adds value without redundancy.

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

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

Given simple schema (2 params, no output schema), description covers what the tool does, when to use, parameter examples, and return format (IDs + URIs). Complete 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?

Input schema has 100% coverage with descriptions for both parameters. Description adds context by providing examples (e.g., 'Apple' → AAPL) and explaining value format for different types.

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 states specific verb 'Look up' and resource 'canonical/official identifier for a company or drug', providing examples and context. It distinguishes from sibling tools by focusing on identifier resolution for use with 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 states when to use: 'Use when a user mentions a name and you need the CIK...' and provides ordering guidance: 'Use this BEFORE calling other tools that need official identifiers.'

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, destructiveHint=false, indicating no side effects. The description adds critical behavioral context: return values (verdict types, extracted form, actual value with citation, percent delta), data source (SEC EDGAR + XBRL), and replacement of multiple calls. No contradiction.

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

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

The description is concise (two paragraphs) and front-loaded with purpose and usage. Every sentence adds value: first paragraph states purpose and when to use, second details scope and output. No fluff.

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

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

Given one required parameter and no output schema, the description fully explains input expectations, output structure (verdict, extracted form, value with citation, delta), and domain restriction. The tool is simple enough that the description covers 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?

Schema coverage is 100% with a clear description for the 'claim' parameter. The description adds value with concrete examples (e.g., "Apple's FY2024 revenue was $400 billion") and clarifies it expects natural language, going 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 the tool's purpose: fact-checking natural-language claims against authoritative sources. It specifies the verb (validate, verify) and resource (factual claims), and distinguishes from sibling tools by highlighting efficiency gains (replaces 4-6 sequential calls).

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

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

The description explicitly states when to use the tool (when agent needs to check truth of a user statement) and provides example queries. It sets scope (v1 supports company-financial claims) but does not explicitly state when not to use it or name alternatives among siblings.

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