Orcid

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds that default model is free, Anthropic requires BYO key, and returns per-model {score, confidence, signals, raw_response} plus combined view. 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, well-structured paragraph with no wasted words. It front-loads the primary action, then elaborates on parameters and use cases efficiently.

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

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

Given no output schema, the description adequately summarizes return values (per-model fields + combined view). All 4 parameters are explained, and the tool's purpose and use cases are fully covered. No gaps for the complexity level.

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 explanatory value for each parameter: 'entity' examples, 'models' supported options, '_apiKey' pass-through, 'context' disambiguation. This exceeds basic 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 brand knowledge and scores visibility, with specific verbs 'probe' and 'score'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on general brand checks and offering multiple model probes.

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 lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when to use the _apiKey for Anthropic. However, it does not explicitly state when not to use this tool versus a specific sibling like 'scan_competitor_ai_presence'.

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 behavioral context beyond annotations: it explains that the tool routes to 1,423+ tools, fills arguments, and returns structured answers with stable citation URIs. 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 front-loaded with the key usage instruction and then elaborates with examples. Slightly promotional with numbers, but still concise overall and well-structured.

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

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

Given the simple schema and the tool's broad scope, the description provides sufficient context: what types of questions to route here, expected output format (citations), and internal routing behavior. No output schema, but the description compensates.

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 reinforces appropriate question types but doesn't add new constraints or format details for the single 'question' parameter beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: answering factual questions using structured data from many sources with citations. It distinguishes itself from web search by emphasizing authoritative data and provides a clear verb-resource pair.

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

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

Explicitly instructs 'PREFER OVER WEB SEARCH' and provides extensive examples of when to use (e.g., SEC filings, FDA data, weather) and typical query patterns ('what is', 'look up', 'find'). This makes the tool's usage very clear.

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

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

The description details the multi-step behavior: market resolution, classification, fan-out to data packs, and return of evidence packet with comparison. This adds significant context beyond annotations (readOnly, openWorld), though it could mention what happens if the market is not found.

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, front-loading the purpose and then elaborating on process and examples. It avoids unnecessary fluff but could be slightly more compact.

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 input, processing steps, and output format (evidence packet + comparison). It includes examples of fan-out packs. Without an output schema, more detail on the packet structure might help, but it is sufficient for agent understanding.

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

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

The input schema already has 100% coverage with full descriptions for both parameters. The tool description does not add new meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data in one call. It uses specific verbs and resources, and distinguishes itself by being a core demo product that saves agents from having to discover data packs individually.

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

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

The description provides three explicit use cases ('should I bet on X?', 'what does the data say?', 'is there edge?'), guiding the agent on when to invoke this tool. However, it does not discuss when not to use or contrast with sibling tools like ask_pipeworx or 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?

Discloses data sources (SEC EDGAR/XBRL, FAERS, FDA, trials) and return format (paired data with citation URIs). Aligns with annotations (readOnlyHint, openWorldHint, destructiveHint) and adds context about composite nature of the tool.

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, front-loaded with purpose, and each sentence adds value. It could be slightly more concise but avoids 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?

While the description explains what is returned (paired data + citation URIs), it lacks explicit detail about the exact output structure. Given the lack of an output schema, more detail on the format 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 100% and description adds value by explaining what fields are retrieved for each type and providing concrete examples for the values parameter (tickers/CIKs for companies, drug names).

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

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

The description clearly states it compares 2-5 companies or drugs side by side, specifying the data pulled for each type (financial metrics vs adverse events). It distinguishes itself from sibling tools like search and entity_profile by emphasizing it replaces multiple sequential calls, making its purpose unique.

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 triggers like 'compare X and Y', 'X vs Y', and tables/rankings. Differentiates between company and drug use cases. Lacks explicit exclusion criteria but sufficiently guides when to use.

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

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

Annotations already indicate read-only, non-destructive. Description adds that it returns top-N most relevant tools with names+descriptions, which is useful beyond annotations.

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

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

Concise, front-loaded with purpose. Every sentence adds value; no wasted words.

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

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

No output schema, but description adequately explains return value (top-N tools with names+descriptions). Complete for browsing/discovery 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 100%. Description adds context: default limit 20, max 50, and example queries (e.g., 'analyze housing market trends'), enriching the parameter definitions.

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+resource: 'Find tools' by describing data/task. Examples of domains (SEC filings, FDA drugs) distinguish from siblings like 'search', 'validate_claim'.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use guidance.

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, so the description adds no new behavioral context. With annotations covering safety, a score of 3 is appropriate for not contradicting or adding extra value.

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 at two words, which is superficially efficient but lacks substantive information, making it insufficient for a single-parameter tool.

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

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

Given the single parameter and lack of output schema, the description is too brief to provide a complete understanding. It fails to explain what the summary contains or how the tool behaves beyond being read-only.

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 includes a required parameter orcid_id with no description (0% schema coverage). The description 'Education summary' does not clarify the parameter's purpose or format, leaving the agent to infer its 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?

The description 'Education summary' is a noun phrase lacking a verb, making it unclear whether the tool retrieves, creates, or updates education data. It provides no specific action or resource differentiation from sibling tools like 'employment' or 'works'.

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 given on when to use this tool versus alternatives such as 'employment' or 'works'. The description does not mention context or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so agents know it's safe. However, the description adds no additional behavioral context, such as what happens if the orcid_id is missing or invalid, or any side effects.

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

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

The description is extremely short (two words), but it sacrifices necessary detail for brevity. It is not well-structured and fails to convey essential 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?

Even for a simple tool with one parameter and annotations covering safety, the description is insufficient. It does not explain what the tool returns or how to effectively use it, leaving major gaps.

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

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

The input schema has one parameter 'orcid_id' with no description (0% coverage). The description does not mention this parameter at all, providing no additional meaning beyond the schema.

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

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

The description 'Employment summary' is vague and does not specify what action the tool performs. It lacks a verb and does not clarify whether it retrieves, updates, or deletes employment data. It also does not distinguish it from sibling tools like 'work' or 'education'.

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?

There is no guidance on when to use this tool versus alternatives. The description does not mention any prerequisites, context, or exclusions, leaving the 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 readOnly and non-destructive; the description adds valuable detail on what is returned (SEC filings, financials, patents, news, LEI) and mentions citation URIs. This goes beyond annotations without contradicting them.

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

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

The description is well-structured: purpose first, then usage examples, return content, and input specifics. Every sentence adds value; no wasted words.

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

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

No output schema exists, so the description fully compensates by listing all return types (SEC filings, fundamentals, patents, news, LEI) and citation URIs. It also explains input handling and edge cases (names).

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 nuance: 'type' explains only 'company' supported with future plans; 'value' clarifies ticker/CIK vs names and recommends 'resolve_entity' for names. This is useful 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 'Get everything about a company in one call' and provides multiple natural language query examples (e.g., 'tell me about X', 'research Microsoft'). It distinguishes itself from siblings like 'resolve_entity' by noting it replaces 10+ pack tools across SEC, USPTO, etc.

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 when to use (user asks for company profile) and when not to use names directly ('use resolve_entity first if you only have a name'). It provides clear context and alternatives, though it could explicitly state when to avoid this tool in favor of others.

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

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

Annotations already provide destructiveHint=true, and description confirms deletion. Adds context about clearing sensitive data, but lacks details on error handling or irreversibility beyond what annotations imply.

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

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

Two sentences, front-loaded with core action and usage context. 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 simple tool (1 param, no output schema) and annotations, the description is complete: states purpose, usage, and pairs with 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 has 100% description coverage for the only parameter 'key' as 'Memory key to delete'. Description adds no additional semantic value beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key', specifying the verb (delete), resource (memory), and method (by key). It differentiates 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 states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with 'remember' and 'recall' as 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 declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. Description confirms non-destructive fetching and adds details about output format and placement, adding 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?

Front-loaded with the key action, then expands with details. Could be slightly more concise, but every sentence contributes meaningfully.

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

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

No output schema, but description explains output is a text blob in llms.txt format. Covers functionality and output adequately for a read-only, idempotent 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%, so the schema already documents parameters. Description adds context about the process (fetches, extracts) but no extra semantic detail 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 the tool generates a production-ready llms.txt file for any URL, distinguishing it from siblings like ai_visibility_check or scan_competitor_ai_presence by focusing on a specific output format.

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

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

Explicitly provides use cases (indexing, drafting, auditing), giving agents context on when to apply. Does not state exclusions, but the guidance is clear enough.

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

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

The description goes beyond the annotations by disclosing that the tool is 'Free; doesn't count against your tool-call quota' and 'rate-limited to 5 per identifier per day.' It also mentions that 'the team reads digests daily and signal directly affects roadmap,' giving insight into how feedback is processed. Annotations are neutral (readOnlyHint false, destructiveHint false), so 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 approximately 100 words and is well-structured. It front-loads the main purpose, then lists when to use, constraints, team usage, and rate limits. Every sentence is meaningful with no redundant information. It achieves maximum information density 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?

Given the tool has 3 parameters (one nested), no output schema, and comprehensive schema descriptions, the description provides all necessary context. It covers usage guidelines, behavioral nuances (rate limits, quota impact), and content constraints. The agent has enough information to determine when and how to invoke the tool correctly.

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

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

The input schema already provides good descriptions for all parameters (100% coverage). The description adds extra value by explaining the message format ('Be specific (which tool, what error, what data was missing). 1-2 sentences typical, 2000 chars max') and clarifying that the context object is optional. This enhances the agent's understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the types of feedback (bug, feature, data_gap, praise) and uses a specific verb ('feedback'). This distinguishes it from sibling tools that are for querying or comparing data, not for providing feedback to the team.

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: '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 provides instructions on what to include and avoid (e.g., 'don't paste the end-user's prompt'). While it doesn't explicitly state when not to use it, the guidelines are clear and comprehensive.

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

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

Beyond annotations (readOnlyHint=true, idempotentHint=true, etc.), the description adds valuable behavioral context: it explains the data source (CF analytics-engine), PII handling (none), and caching policy (5min-1h). This enriches understanding beyond structured metadata.

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 key sentences plus bullet-style usage list) and front-loads the core purpose. Every sentence adds value, with no redundancy or 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?

Despite no output schema, the description adequately explains the return format (top tools, packs, call volume) and provides context about caching and data derivation. It is complete enough for an agent to understand what to expect.

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

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

The single parameter 'window' has 100% schema coverage and a description that elaborates on the meaning of each enum value (short vs. long windows). This adds semantic value beyond the enum list, justifying a score above baseline 3.

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

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

The description clearly states the tool returns top tools, packs, and call volume over a recent window. It uses specific verbs ('returns') and resources ('top tools, top packs, total call volume'), and distinguishes itself from sibling tools (e.g., discover_tools) by focusing on trending activity aggregated from other AI agents.

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

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

The description explicitly lists three useful scenarios for using the tool, providing clear context. It lacks explicit 'when not to use' or direct comparison to siblings, but the use cases are specific enough to guide appropriate invocation.

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

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

The description explains the underlying logic (monotonicity violations), what it checks (date/threshold ordering), and the output format. Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds useful behavioral context beyond them. 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 well-structured, starting with a clear purpose statement, then explaining the concept, and finally describing the output. Each sentence adds value, though it 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?

Given the simple input (1 parameter) and no output schema, the description covers input, logic, and output format adequately. It explains what the tool returns (list of entries with fields). It is sufficiently complete for an agent to invoke correctly.

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

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

With 100% schema description coverage, baseline is 3. The description adds meaning by explaining how the 'event' parameter is used (e.g., 'the tool walks the child markets') and provides an example format, enhancing the bare schema 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: 'Find arbitrage opportunities within a Polymarket event by checking for monotonicity violations.' It provides a concrete example and specifies the input (event slug or URL), making it distinct from siblings like 'polymarket_edges'.

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

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

The description implies usage when one wants to find arbitrage opportunities, but it does not explicitly state when to use this tool versus alternatives like 'polymarket_edges' or other sibling tools. No exclusions or alternative suggestions are provided.

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

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

The description adds significant behavioral detail beyond annotations (readOnlyHint, openWorldHint, destructiveHint). It explains the scanning, grouping, caching of price history, computation of model probability, and ranking by edge magnitude. No contradiction with annotations; the tool is read-only and open-world, which aligns with the description.

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 5 sentences, well-structured with action, process, and output. It front-loads the purpose and includes necessary details without being verbose. Minor room for tightening, but effectively communicates the tool's functionality.

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 states it returns top N ranked by edge magnitude with suggested trade direction. It covers the model scope (crypto-price bets V1), efficiency (fetches price once), and use case. Annotations provide safety context. Complete for a discovery 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% with clear descriptions for limit, window, and min_edge_pp. The description adds context on how these parameters are used (e.g., default/max values for limit, volume window for filtering) and explains the overall ranking process, providing extra value beyond the schema alone.

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

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

The description clearly states the tool scans high-volume Polymarket markets and returns those where Pipeworx data disagrees with market price, including the model used (lognormal from FRED + coinpaprika) and the process (groups by asset, fetches price history once, computes probability, ranks by edge). It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge detection for betting opportunities.

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

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

The description explicitly states it's built for the 'what should I bet on today' question and helps agents discover opportunities without manual paging. It provides clear context for use but lacks explicit exclusions or alternatives, though sibling tools like bet_research and polymarket_arbitrage imply different 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, idempotentHint, and destructiveHint. The description adds context about the spread calculation and modes but does not disclose additional behavioral traits like rate limits or data freshness.

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 front-loaded core idea and clear breakdown of modes. Slightly verbose but every sentence adds value.

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

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

Covers the main use case, return values, and modes. Lacks mention of error scenarios or what happens if a topic is not found, but adequate for a read-only 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%, and the description adds significant meaning: explains the two modes, how explicit parameters override topic-mapped ones, and provides ticker format examples.

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

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

The description clearly states it provides cross-venue spread between Kalshi and Polymarket for the same event. It specifies two modes and the output, distinguishing it from siblings like polymarket_arbitrage.

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

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

The description explains two modes (topic shortcuts and explicit tickers) and when to use each, but does not explicitly exclude alternatives or discuss when not 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 indicate read-only and non-destructive behavior; description adds scoping detail and relationship to sibling tools, enhancing transparency 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?

Three sentences, front-loaded with purpose, each adding distinct information (usage, scoping, pairing). No wasted words.

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

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

No output schema, but description implies return values (saved value or key list). For a simple retrieve tool with good annotations, coverage is adequate.

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

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

Schema covers the optional 'key' parameter 100%; description adds the crucial behavior that omitting key lists all keys, providing value beyond schema.

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

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

The description clearly states the tool retrieves values saved via 'remember' or lists all keys when key is omitted, distinguishing it from siblings like 'remember' and 'forget'.

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

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

Explicitly describes when to use (retrieving stored context) and implies alternatives (pairing with remember/forget). Provides context on scoping but lacks explicit when-not-to-use instructions.

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 (readOnlyHint=true, destructiveHint=false) are consistent. The description adds significant behavioral context: parallel fan-out to three sources, return format (structured changes, total_changes count, citation URIs), and parameter format details. 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 main sentences plus pertinent details) and front-loads the core purpose. Every sentence provides necessary information without 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?

The description covers all key aspects: purpose, parameters, sources, and return structure. Slight room for minor details like error handling or limits, but it's complete enough for effective tool selection and invocation.

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

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

Schema coverage is 100%, but the description adds extra meaning: explains 'since' accepts ISO dates or relative shorthands with examples, and 'value' accepts ticker or CIK. This enhances schema descriptions.

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

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

The description clearly states the tool's purpose: retrieving recent changes for a company. It provides specific verb phrases ('what's happening with X?', 'any updates on Y?') and distinguishes itself from sibling tools like entity_profile or search by emphasizing multi-source fan-out (SEC, GDELT, USPTO).

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 usage examples and specific query patterns, but does not explicitly state when not to use or mention alternatives. However, the examples clearly indicate appropriate contexts for invocation.

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, destructiveHint=false, so the safety profile is clear. The description adds little beyond stating it returns the 'full public record', which is already implied by the name. No additional behavioral traits are disclosed.

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

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

The description is a single sentence that immediately conveys the core purpose. It is front-loaded and contains no extraneous information.

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

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

For a simple lookup tool with one parameter and clear annotations, the description is reasonably complete. It specifies the input format and the scope of the output (full public record). No output schema is present, but the description sufficiently covers what the tool does.

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% description coverage for the parameter, but the description provides an example format (e.g., '0000-0001-5109-3700'), which adds meaningful context beyond the parameter name alone. This compensates well for the schema 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 the tool's purpose: returning a full public record given an ORCID iD. It uses a specific verb (implied retrieval) and resource (public record), and distinguishes itself from siblings like 'work' or 'education' which are specific subsets.

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 its siblings. The description does not mention alternatives or exclusion criteria, leaving the agent without context for tool selection.

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

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

Annotations indicate readOnlyHint=false (write), destructiveHint=false. Description adds scoping by identifier, persistent for authenticated users, 24-hour for anonymous sessions. No contradictions.

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

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

Three sentences, front-loaded with purpose, then usage, then behavior. No wasted words.

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

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

Enough information for a simple 2-param store operation. No output schema needed. Usage guidance and behavioral notes are complete.

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

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

Schema coverage is 100% with descriptions; the description doesn't add new parameter-level details beyond the schema examples. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, with specific examples (resolved ticker, address, preference). It distinguishes from siblings like 'recall' and 'forget'.

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

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

Explicitly says when to use (discover something worth carrying forward) and pairs with 'recall' and 'forget'. No explicit when-not, but the context is clear enough.

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

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

Annotations indicate read-only and non-destructive behavior. The description adds context by detailing that the tool returns IDs plus citation URIs, and provides examples of outputs. No contradictions, though rate limits or error handling are not mentioned.

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 cover all necessary information without redundancy. The main purpose is front-loaded, and 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?

Given no output schema, the description adequately explains the return format (IDs + citation URIs) and provides workflow guidance. The two parameters are well documented, so the description is complete for this 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 already describes parameters with 100% coverage. The description enriches this with concrete examples for both parameters (e.g., 'AAPL', 'ozempic') and clarifies the accepted values for the 'type' parameter.

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

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

The description clearly states the purpose: 'Look up the canonical/official identifier for a company or drug.' It provides specific examples and distinguishes the tool from siblings by noting it replaces multiple lookup calls and is a prerequisite for other tools.

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

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

Explicitly specifies when to use the tool ('Use when a user mentions a name and you need the CIK...') and advises to use it before other tools requiring official identifiers. Implicitly distinguishes from alternatives by stating it replaces 2–3 lookup calls.

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 transparently discloses the tool's behavior: it probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized. It also describes the return format: ranked list with score, confidence, and signal density per entity. Annotations already indicate readOnly, idempotent, and non-destructive, and the description aligns with these without contradiction.

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

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

The description is concise and well-structured: two main sentences plus a short example in quotes. The first sentence delivers the core purpose, the second adds behavioral detail, and the example provides concrete context. No unnecessary words; every sentence adds value.

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

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

Given the tool's complexity (multiple entities, probing, ranking) and no output schema, the description adequately covers the return values (ranked list with score, confidence, signal density) and the subject/competitor distinction. However, it does not explain what 'signal density' means or mention limits like the maximum of 8 entities, which are present in the schema but not elaborated. Slight room for improvement.

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?

Despite 100% schema coverage, the description adds significant meaning beyond the schema. It explains that the first entity in the entities array is treated as the 'subject' for narrative and the rest as competitors. It also adds usage nuances like 'Omit for just workers-ai' for the models parameter. These details are not in the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and scope (multiple entities). It also distinguishes from sibling tool ai_visibility_check by implying a multi-entity comparison, and from compare_entities by focusing on AI visibility. The example further clarifies the use case.

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 usage guidance by stating 'Useful for competitive AI-marketing audits' and giving an example query. It implies when to use this tool (multi-entity comparison) vs ai_visibility_check (single entity). However, it does not explicitly mention when not to use it or name alternative tools like compare_entities, leaving some room for interpretation.

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 behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed list. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint all consistent).

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

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

The description is a single paragraph but well-structured, covering key points. It could be slightly more concise, but the information density is high and efficiently 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 no output schema, the description fully covers return values (summary block, advisories, links, alternate versions), limitations (NPM only, timeout), and error handling (sources_failed). 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% with descriptions already present. The description reiterates package name and version default but adds no new semantic 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 it is a composite check for adding an npm package, covering deps.dev and bundlephobia. It specifies the return fields and distinguishes itself from siblings by being a unified call for safety, popularity, and size evaluations.

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

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

Explicitly says when to use: when an agent asks about safety/popularity/size or cost of adding a package. It also notes limitations (NPM only v1) and alternatives (deps.dev directly for other ecosystems), providing clear usage guidance.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds minimal behavioral context ('Solr-style query') 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?

Single sentence conveying purpose efficiently with no redundant information. However, it is slightly too brief given the tool's complexity.

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

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

No output schema or explanation of return format, pagination, or query syntax details. Despite good annotations, the description is minimal for a search tool with multiple parameters.

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

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

Input schema has 100% coverage with clear descriptions for all three parameters. The description does not add additional meaning 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 identifies a specific action ('search') and resource ('ORCID Registry'), and distinguishes from sibling tools like 'entity_profile' or 'record' that serve different purposes.

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. Sibling tools such as 'entity_profile' or 'record' might be more appropriate for direct lookups, but the description does not mention exclusions or context.

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

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

Annotations declare readOnlyHint, openWorldHint, and destructiveHint. The description adds specifics: returns a verdict, extracted structured form, actual value with citation, and percent delta. It also notes the tool's efficiency by replacing multiple calls, providing behavioral context beyond annotations.

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

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

The description is a single paragraph but packs essential information without redundancy. Every sentence adds value, though a more structured format could improve scannability.

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

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

No output schema exists, but the description details return values (verdict types, citation, percent delta) and explains the tool's role as a replacement for multiple steps. It mentions scope limitations ('v1 supports company-financial claims'), but could also discuss error handling or edge cases.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's parameter information is limited to example phrasings already in the schema. It does not add significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: fact-checking factual claims against authoritative sources, specifically company financial claims using SEC EDGAR. It also distinguishes from siblings by explaining it replaces multiple 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 says 'Use when an agent needs to check whether something a user said is true' and provides example phrasings. It also states the scope (v1 supports company-financial claims). It lacks exclusion criteria or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds no extra behavioral details (e.g., error handling for missing put-code, authentication needs). Since annotations cover the basic safety profile, the description is adequate but not enriched.

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 omits essential information (no verb, no parameter explanation). Conciseness is not rewarded when it sacrifices meaning; the sentence barely earns its place.

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

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

For a simple retrieval tool with 2 required parameters, the description lacks context on the return format, error handling, and the relationship between orcid_id and put_code. An agent has insufficient information to use the tool effectively.

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 0% description coverage for parameters, and the description only implies put-code as key, ignoring orcid_id. It does not explain the relationship between the two parameters or their formats. With no parameter details in schema, the description fails to compensate.

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 indicates that the tool retrieves a single work record by put-code. The name 'work' and singular phrasing differentiate it from sibling 'works' (which likely lists). However, it lacks a verb like 'get' or 'retrieve', which slightly reduces clarity.

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. The description does not mention when to use it instead of 'works' (list) or other sibling tools, nor does it specify prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds that it returns 'summaries with put-codes', which hints at output format but lacks details like pagination or data completeness. Overall adequate but not enriched beyond annotations.

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

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

The description is extremely brief (one phrase), which is concise but under-specified. It omits essential information, leading to a trade-off between brevity and completeness. Every sentence should earn its place; here, a single sentence is insufficient.

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, no output schema, and no parameter descriptions, the description fails to provide complete context. It doesn't clarify the nature of 'put-codes', expected output structure, or any behavioral nuances beyond a basic summary.

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%, and the tool description does not explain the sole parameter 'orcid_id' at all. The agent receives no guidance on its purpose or format, forcing reliance on external knowledge. This is a critical 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 'Works (publication) summaries with put-codes' indicates the tool returns summaries of publications, but it is vague: 'put-codes' is undefined and the exact nature of summaries is unclear. It subtly distinguishes from the sibling 'work' by implying multiple publications, 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 or alternatives. The description does not mention context, prerequisites, or conditions for use, leaving the agent without decision support.

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