Eia

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

No annotations are provided, so the description bears full responsibility. It discloses that Pipeworx 'picks the right tool, fills the arguments, and returns the result' – indicating autonomous decision-making and no direct user control over which tool is used. This is a key behavioral trait. However, it does not mention potential limitations like accuracy, latency, or the possibility of the tool failing to find a source.

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

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

The description is concise (three sentences) and front-loaded with the core action. It includes examples for clarity. However, it could be slightly tighter – the second sentence repeats the idea of delegation already implied in the first. Still, it is efficient overall.

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

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

Given the tool's simplicity (one string parameter, no output schema), the description is fairly complete. It covers purpose, usage, and examples. A minor gap: it doesn't explain what happens if the question cannot be answered or which tools might be used. But overall, it provides sufficient context for an agent to decide when to invoke it.

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

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

Schema coverage is 100%, so the schema already documents the 'question' parameter. The description adds value by framing the parameter as natural language input and giving examples, but this is more illustrative than adding technical semantics. A 3 is appropriate as the description reinforces schema information without significantly extending it.

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 natural language questions by automatically selecting the best data source and filling arguments. It uses a specific verb-resource pair ('Ask a question' and 'get an answer') and distinguishes itself from siblings by acting as an orchestrator that delegates to 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?

The description explicitly tells when to use this tool: when you want to 'just describe what you need' without browsing tools or learning schemas. It contrasts with sibling tools that are domain-specific (e.g., eia_* for energy data) by offering a general question-answering interface. Examples clarify 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?

With no annotations, the description carries full burden. It specifies return data and resource URIs but does not disclose whether it is read-only, requires authentication, or has rate limits, which are typical for such tools.

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 with no filler: first states core purpose, second details types, third mentions returns and efficiency. Could be slightly more concise by merging sentences, but overall 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 no output schema and full parameter coverage, the description adequately covers what the tool does, what data it returns, and the entity types. Missing hints about prerequisites or limitations, but sufficient for basic usage.

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

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

Schema coverage is 100% (baseline 3). The description adds value by explaining the type enum and providing examples of values (e.g., tickers for company, drug names), making it easier for the agent to construct valid inputs.

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 it compares 2–5 entities side by side, distinguishes between company and drug types with specific data fields, and is clearly distinct from sibling tools like eia_* or ask_pipeworx.

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

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

The description notes it replaces 8–15 sequential calls, implying efficiency for batch comparisons, but does not explicitly state when to avoid using it or compare it with alternative tools like ask_pipeworx.

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 mentions the tool returns 'the most relevant tools with names and descriptions,' but does not detail the exact behavior of the search algorithm (e.g., whether it uses semantic similarity). No annotations are provided, so the description carries the full burden. It could mention that results are ranked by relevance, but overall it gives a reasonable expectation.

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

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

The description is two sentences, front-loaded with the main action, and every sentence adds value. No wasted words. The examples in the input schema are also helpful but not part of the description itself.

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 that the tool has 2 parameters, no output schema, and no annotations, the description is sufficient. It explains when to use it, what it does, and how to query it. The context signals show it is a search tool, and the description covers the key aspects for an agent to use it 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 description coverage is 100%, so the schema already describes both parameters (query and limit) clearly. The description adds context by providing example queries ('analyze housing market trends'), which helps the agent formulate effective queries. However, it does not add significant new 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 the tool's purpose: 'Search the Pipeworx tool catalog by describing what you need.' It specifies the action (search), the resource (tool catalog), and the method (natural language description). The sibling tools like ask_pipeworx, eia_electricity, etc. are domain-specific, while discover_tools is a meta-tool for finding other tools, so it is well-differentiated.

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 this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This clearly indicates it should be used before other tools to narrow down the selection. The sibling tools are specific data tools, so the agent understands this is the discovery 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?

With no annotations, the description must disclose behavioral traits. It mentions data types (generation, sales, prices) but does not describe side effects (none, as read-only), required permissions, rate limits, or return format. The lack of any annotations places the burden on the description, which partially meets it by listing data categories.

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 sentences clearly stating the tool's purpose and scope. It is front-loaded with the verb 'Get' and resource 'electricity data', with a short list of example fuel types. 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 5 parameters (2 required) and no output schema, the description covers the data categories but omits details on date format, frequency options, or response structure. It is adequate for a simple data retrieval tool but could clarify output expectations.

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 100% coverage via descriptions, so the description adds no new param info beyond listing data categories. The description's list of fuel sources and data types complements the schema's series parameter enum values, but does not add meaning 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 retrieves electricity data covering generation by fuel source, retail sales, and prices. It names specific fuel types, but does not distinguish it from sibling tools like eia_natural_gas or eia_ethanol, which likely have similar scope for different energy types.

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

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

No guidance is provided on when to use this tool vs alternatives like eia_series (general series query) or sibling fuel-specific tools. The description implies it is for electricity data but does not explain when to prefer this over other EIA tools.

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

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

With no annotations, the description partially covers behavioral aspects by explaining the data source (EIA petroleum supply filtered for ethanol) and product code (EPOOXE). However, it does not disclose rate limits, authentication requirements, or any destructive operations.

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

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

The description is three sentences long, front-loaded with the main purpose, and every sentence adds value. No fluff 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?

Given the tool's moderate complexity (5 parameters, no output schema, no annotations), the description provides enough context to use the tool effectively. It explains the data origin and key series values, which compensates for the lack of output schema and annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about the series parameter values (production, stocks, imports) and mentions frequency defaults, but does not elaborate on date format or API key usage 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 retrieves fuel ethanol data covering production volumes, stock levels, and imports. It distinguishes itself from other EIA tools by specifying the focus on ethanol and the underlying EIA petroleum supply data.

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

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

The description implies the tool is for ethanol-specific data but does not explicitly state when to use it over siblings like eia_petroleum or eia_series. No alternatives or exclusions are mentioned.

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

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

Annotations are empty, so the description must carry behavioral transparency. It lists output categories (prices, production, etc.) but does not disclose whether data is read-only, any rate limits, or how the API key is used. No destructive behavior is implied, so a neutral score is fair.

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

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

Two concise sentences, front-loaded with purpose and concrete examples. No fluff; every phrase 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 moderate complexity (5 parameters, no output schema, no nested objects), the description adequately covers the tool's purpose and data types. It lacks explicit return format info, but the listed categories suffice for an agent to decide. Slightly more detail on date format or frequency could improve, but not necessary.

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 adds context by listing example series values and mentioning specific data types (Henry Hub), but does not elaborate on start/end date format, frequency options, or _apiKey usage 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?

Clearly states the tool returns natural gas data and enumerates specific data types (prices, production, consumption, storage) with examples (Henry Hub spot prices, underground storage). This distinctively positions it against siblings like eia_electricity or eia_petroleum.

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 for accessing natural gas metrics, but does not explicitly contrast with siblings like eia_series (which might offer different aggregation) or advise when not to use it. No guidance on required API key setup or series selection constraints.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool fetches data and lists the product types, which is useful. However, it does not mention any behavioral traits such as rate limits, authentication requirements beyond the API key, or the structure of the response. It also does not clarify default behaviors like default frequency or date ranges.

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

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

The description is two sentences long, front-loads the main action and resource, and lists the categories efficiently. Every sentence is informative and there is no unnecessary text.

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

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

The tool has 5 parameters with 100% schema coverage, no output schema, and no annotations. The description covers the core purpose and product types but lacks details on response format, error handling, or behavior with optional parameters. Given the moderate complexity, the description is adequate but not comprehensive.

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

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

The schema has 100% description coverage, so the baseline is 3. The description adds value by summarizing the overall purpose and listing the product categories, but it does not explain the 'end' and 'start' date parameters or the 'frequency' parameter beyond what the schema already provides. Since the schema already describes each parameter well, the description's additional context is limited but not redundant.

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

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

The description uses a specific verb ('Get') and clearly identifies the resource ('petroleum/fuel data') with a comprehensive list of sub-categories (gasoline prices, diesel prices, etc.). It also distinguishes itself from siblings by stating it is a 'simplified interface to common EIA petroleum series,' which contrasts with other EIA tools for electricity, ethanol, natural gas, and the more general eia_series.

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 by stating it's a 'simplified interface to common EIA petroleum series,' suggesting it is for common queries rather than all series. However, it does not explicitly state when to use this tool versus eia_series or other siblings, nor does it mention 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 are empty, so the description carries the burden. It states the tool returns time series with period, value, and metadata, but does not disclose if it is read-only, destructive, or requires authentication beyond the API key. The description is adequate but not detailed.

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

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

The description is reasonably concise, providing essential information in a few sentences. It front-loads the purpose and includes examples, though it could be slightly more succinct.

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 a generic data retrieval tool and the lack of output schema, the description provides basic completeness. It explains the route structure and return format, but could include more details about common use cases or error handling.

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 adds examples of route paths but does not elaborate on the meaning of parameters beyond the schema's descriptions.

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

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

The description clearly states the tool retrieves EIA time series data by route path, and provides multiple examples of route paths. However, it does not differentiate this tool from sibling tools like eia_petroleum, eia_natural_gas, etc., which may have overlapping functionality.

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 for any EIA time series data via route paths, but does not specify when to use this generic tool versus the more specific sibling tools (e.g., eia_petroleum). There is no guidance on when not to use it or 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?

No annotations provided, so description carries full burden. It correctly indicates destructive behavior ('Delete'), but lacks details on confirmation, reversibility, or side effects. Adequate but minimal.

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 with zero waste. Clear and front-loaded action word.

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 (1 param, no output schema, no enums) and no annotations, the description is adequate but could specify whether the key must exist or if deletion fails silently.

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% (only one parameter 'key' is described in schema). Description adds no extra meaning beyond schema, so baseline 3 is appropriate.

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

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

Description states verb 'Delete' and resource 'a stored memory by key', clearly indicating the tool's action and target. It distinguishes from sibling tools like 'recall' and 'remember'.

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 vs alternatives (e.g., 'remember' for storing, 'recall' for retrieval). Context is implied but no explicit exclusions or alternative naming.

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?

Without annotations, the description bears full responsibility for behavioral disclosure. It discloses the rate limit ('5 messages per identifier per day') and the fact that it is 'Free.' It also instructs not to include prompt verbatim. No destructive behavior is implied for a feedback tool, so transparency is adequate.

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

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

The description is two sentences plus a rate-limit note, all front-loaded and concise. Every sentence adds value: purpose, usage examples, guidance on content, rate limit. 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?

The tool is simple (feedback submission) with no output schema. The description covers purpose, input guidance, and behavioral constraints (rate limit). It does not describe the return value or error handling, but for a feedback tool this is acceptable. Overall, it provides sufficient context for an agent to use it correctly.

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

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

The input schema has 100% description coverage, providing detailed enum values for 'type' and guidance for 'message' and 'context'. The description adds extra context like 'Do not include the end-user's prompt verbatim' and the rate limit, which goes beyond the schema. This adds value for the agent.

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: 'Send feedback to the Pipeworx team.' It lists specific use cases (bug reports, feature requests, etc.), making it distinct from sibling tools which are data retrieval or memory related.

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 tells when to use the tool (e.g., for bug reports) and provides guidance on what to include ('Describe what you tried in terms of Pipeworx tools/data') and what to avoid ('do not include the end-user's prompt verbatim'). It also mentions a rate limit. However, it does not explicitly state alternatives or when not to use it, though siblings are clearly different.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool retrieves or lists memories, but does not mention whether retrieval is read-only, any limitations on session persistence, or error handling for missing keys.

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 sentences with no wasted words. It front-loads the primary action and follows with usage guidance.

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 is simple with one optional parameter and no output schema, the description is fairly complete. However, it lacks information about return format, error cases (e.g., key not found), and scope of session persistence.

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

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

The input schema already describes the parameter 'key' with a description. The description adds context that omitting the key lists all memories, which is useful but the schema already covers the parameter's purpose. Schema coverage is 100%, so baseline is 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 retrieves a memory by key or lists all memories when key is omitted. It distinguishes from 'remember' (store) and 'forget' (delete), but 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?

The description provides guidance on when to use the tool (to retrieve context saved earlier) and when to omit the key (to list all). However, it does not explicitly mention when not to use it or 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?

No annotations provided, so description carries full burden. Discloses memory persistence difference between authenticated users (persistent) and anonymous sessions (24 hours). This adds behavioral context beyond the schema.

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

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

Three concise sentences with no wasted words. Front-loaded with action, then usage context, then behavioral note. 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 simplicity of the tool (2 required string params, no output schema), the description is largely complete. It covers purpose, usage, and behavior. A minor gap: does not mention that the value is overwritten if the key already exists, which is implied but not explicit.

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 does not add additional meaning beyond what the schema already provides for key and value. The examples in the schema ('subject_property', etc.) already give context.

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

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

Clearly states 'Store a key-value pair in your session memory' with specific verb (store) and resource (session memory). Distinguishes from siblings like 'recall' and 'forget' by focusing on writing to memory.

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

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

Explicitly says 'Use this to save intermediate findings, user preferences, or context across tool calls', providing clear context for use. However, does not mention when not to use or alternatives among siblings.

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

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

No annotations are provided, so the description carries the full burden. It explains the return values (ticker, CIK, company name, URIs) and the v1 limitation. It lacks details on side effects, auth, or rate limits, but for a read-only resolver this is adequate.

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

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

The description is approximately 50 words, front-loaded with the main purpose, and each sentence adds value. It is concise without sacrificing 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?

Despite no output schema and no annotations, the description covers purpose, input details, examples, and efficiency benefit. It does not discuss error handling, but the schema and examples provide sufficient context for a simple resolver 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 both parameters described. The description adds further meaning by providing examples ('AAPL', '0000320193', 'Apple') and clarifying the accepted formats, which exceeds the schema alone.

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

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

The description clearly states the verb 'Resolve' and the resource 'entity to canonical IDs across Pipeworx data sources'. It specifies the supported type (company) and input formats (ticker, CIK, name), making it distinct from siblings like ask_pipeworx or data-specific 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?

The description explicitly states that the tool 'Replaces 2–3 lookup calls', guiding the agent to use it instead of multiple calls. While it doesn't mention when not to use it, the context is clear and helpful.

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