TroyStack

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

With no annotations, the description carries the full burden. It implies a mutating operation ('Add') but does not disclose authentication requirements (api_key is required), reversibility, or any side effects on the portfolio. This is a significant gap for a write 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 a single concise sentence with no fluff, and it is front-loaded with the action. However, it is extremely minimal for a tool with seven parameters, though this dimension rewards efficiency.

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 is too sparse for a mutation tool with no annotations or output schema. It lacks details on return values, authentication, and use cases. The parameters are covered by the schema, but overall context is incomplete.

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

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

Schema description coverage is 100%, so parameters are already well documented. The description adds no additional parameter context, which is acceptable given the rich schema.

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

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

The description uses the verb 'Add' with the resource 'precious metals purchase' and destination 'portfolio', clearly conveying the action. It distinguishes from the sibling get_* tools, though it could more explicitly separate from scan_receipt.

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

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

No guidance is provided on when to use this tool versus alternatives like scan_receipt. There is no mention of prerequisites or scenarios where manual entry is preferable.

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 the full transparency burden. It discloses a key behavioral trait: the presence or absence of api_key changes the nature of the answer (personalized vs. general). It also defines the domain scope ('anything about precious metals, markets, your stack'). This adds meaningful context beyond the bare parameter 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?

Two sentences, each earning its place. The first states the purpose, the second explains the optional parameter's usage. No unnecessary detail or repetition. Front-loaded with the verb and resource.

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

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

For a simple chat tool with two parameters and no output schema, the description covers the essentials: what it does, the domain, and how the optional parameter affects behavior. It does not describe the return format, but for a conversational tool this is largely implicit. Overall, sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the behavioral consequence of omitting api_key ('or omit for general market analysis'), which the schema alone does not fully convey. The message parameter is self-evident, but the description's clarification of the optional parameter's effect earns a 4.

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: 'Ask Troy anything about precious metals, markets, your stack.' It uses a specific verb ('Ask') and identifies the resource ('Troy'), while distinguishing it from sibling data-retrieval tools by positioning it as an interactive chat/Q&A interface.

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 clear context on when to use the tool: for asking questions about precious metals, markets, or one's stack. It also gives guidance on the optional api_key parameter ('Provide api_key for personalized portfolio-aware answers, or omit for general market analysis'), though it does not explicitly exclude alternatives or name specific sibling tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It names output fields but does not state whether the operation is read-only, what authentication is needed beyond the api_key parameter, or any other behavioral traits. This is a significant transparency gap.

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 short noun phrase, not a complete sentence, which is concise and without fluff. However, it is under-specified, lacking a verb and any structural framing that would make it a proper tool description.

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

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

For a simple tool with one parameter and no output schema, the description does list the expected return metrics (cost basis, average cost per oz, break-even price, unrealized P/L per metal) and notes 'per metal' grouping. Yet it omits the response shape, whether it shows all metals or requires filters, and any usage context, leaving it adequate but sparse.

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

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

The schema has 100% coverage for the single api_key parameter with a clear description, so the baseline is 3. The description does not add any additional parameter meaning beyond what the schema already states.

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 lists specific analytics metrics (cost basis, average cost per oz, break-even price, unrealized P/L per metal) which clearly indicates the tool's function, and it distinguishes itself from siblings like get_portfolio and get_speculation by focusing on these valuation metrics. However, it lacks an explicit verb, relying on the title 'Get Portfolio Analytics' to convey the action.

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

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

There is no guidance on when to use this tool versus alternatives such as get_portfolio or get_daily_brief. No context, prerequisites, or exclusions are provided, leaving the agent to infer usage solely from the metric list.

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 carry the burden. It discloses that the response varies based on whether api_key is provided (personalized vs. generic synthesis), which is useful. However, it does not mention what happens with an invalid api_key, data freshness, or whether any side effects occur (though presumably read-only).

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 and immediately states the tool's purpose, then explains parameter behavior. There is no fluff or redundant information, making it efficiently front-loaded.

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

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

Given the simplicity (one optional parameter, no output schema, no annotations), the description is adequate but leaves gaps. It does not explain what the brief contains, how recent the data is, or how 'Stack Signal market synthesis' relates to sibling get_stack_signal. For a simple daily brief tool, this might suffice, but more detail on return content would strengthen 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?

The schema only describes api_key as 'TroyStack API key for personalized brief (optional)'. The tool description adds crucial meaning: providing the key yields a personalized brief, while omitting it yields the latest Stack Signal synthesis. This conditional behavior goes beyond the schema's bare 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 provides Troy's daily market brief, with a specific resource and action. It distinguishes between personalized (with api_key) and generic (without) outputs, but does not explicitly differentiate from sibling tools like get_stack_signal which may overlap in content.

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 clear usage guidance for the tool's two modes (provide api_key or omit), but does not say when to use this tool versus alternatives like get_stack_signal. Usage context is implied by the name, but no explicit exclusions or alternative tool references 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?

No annotations are provided, so the description carries the full burden. It only restates the purpose without disclosing the calculation basis, output format, currency, or the fact that it also handles 40% silver Kennedy halves and 35% war nickels. The description adds little beyond the title.

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 is front-loaded with the action and resource. It contains zero redundant or filler wording.

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 parameter schema is detailed, there is no output schema and the description does not mention the return value, spot price integration, or rounding behavior. The 'pre-1965' qualifier is also misleading given the 40% Kennedy parameter. The description is insufficient for a calculation tool of this complexity.

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

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

The schema describes all 6 parameters with silver content per coin (100% coverage). The description adds no additional parameter-level detail, but the schema is fully self-sufficient, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Calculates') and a clear resource ('silver melt value') for 'pre-1965 US coinage', which distinguishes it from siblings like get_spot_prices. However, the description inaccurately says 'pre-1965' while the schema includes 'kennedy_40' (1965-1970) halves, creating ambiguity about the exact coin set.

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 its usage (when silver melt value is needed) but provides no explicit guidance on when to use this tool versus alternatives such as get_spot_prices. No exclusions or alternative tool references 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?

With no annotations provided, the description bears the full burden of behavioral disclosure. It indicates a read operation by listing return values, but does not explicitly state that it is read-only, nor does it mention authentication requirements, rate limits, or error behavior. The description adds some context about the return payload but lacks deeper transparency.

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

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

The description is a single, well-structured sentence that front-loads the primary action and efficiently lists the key data components. Every word contributes meaning, with no filler or redundancy.

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

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

For a simple getter with one parameter and no output schema, the description adequately covers the return values and scopes the tool's purpose. It might have mentioned authentication behavior or error handling, but these are not critical given the simple nature and schema coverage. Overall, the description is sufficiently complete for a portfolio retrieval 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?

The input schema fully documents the only parameter (api_key) with a description 'TroyStack API key (required)', achieving 100% schema description coverage. The tool description adds no additional parameter-specific information, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and a specific resource ('precious metals portfolio'), enumerating the exact data components (total value, cost basis, gain/loss, per-metal breakdown, individual holdings). It is easily distinguished from sibling tools like get_spot_prices or get_analytics, which target different data domains.

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 when to use the tool—whenever an agent needs portfolio information—but does not explicitly state usage context, exclusions, or alternatives. There is no mention of when not to use it or which sibling tool might be more appropriate for related queries. This is implied usage rather than explicit 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?

With no annotations provided, the description must carry the full burden of behavioral disclosure. It simply states 'Historical spot price data' without mentioning return format, default range (1Y), rate limits, or any other behavior beyond the basic definition. This is minimal and does not add context beyond what the name already implies.

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 concise sentence, front-loaded with the core purpose. There is no redundant language or filler; every word contributes to the meaning.

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 with two parameters, both enums with schema descriptions. However, there is no output schema, and the description does not specify the return format, default range, or any edge cases. It is minimally adequate but leaves gaps for a user unfamiliar with the 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 baseline is 3. The description's phrase 'for a precious metal over a time range' merely paraphrases the parameter descriptions and adds no new semantic detail about metal values or range options. It neither enhances nor detracts from 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 function: it retrieves historical spot price data for a precious metal over a time range. The verb 'get' is implied, and the resource and scope are explicit, distinguishing it from sibling tool 'get_spot_prices' which likely provides current prices.

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 historical data retrieval but does not explicitly state when to use it over alternatives like 'get_spot_prices'. It provides context (time range, metal) but lacks explicit when-to-use or when-not-to-use guidance.

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

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

With no annotations, the description must fully explain behavior. It discloses the core calculation logic but does not describe the return format, whether at least one target is required, or any side effects. This is a moderate level of transparency.

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

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

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose. There is no redundant or 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 tool with 4 optional parameters and no output schema, the description lacks specification of the return value and default behavior when no targets are provided. While the core concept is clear, these gaps prevent a higher score.

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 descriptions already document each parameter as a target price per unit (100% coverage). The tool description adds context that these targets are used in multiplier calculations, but this is marginal added value. 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 calculates price multipliers based on hypothetical target prices versus current spot, which is a specific and distinct function. It does not explicitly compare against sibling tools, but the 'hypothetical target prices' distinction sets it apart from spot/history 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?

There is no explicit guidance on when to use this tool versus alternatives like get_spot_prices or get_price_history. The description implies the use case (what-if scenarios) but gives no exclusions or alternative references.

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?

There are no annotations, so the description carries the full burden. It discloses that the tool returns current spot prices and daily change percentages, but it does not mention data source, latency, currency, or whether the operation is read-only (though 'returns' implies it). This is acceptable but not rich.

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 states the action and the precise resource set, with no filler or redundant words. Perfectly front-loaded and efficient.

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

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

For a simple no-parameter read tool without an output schema, the description adequately covers the essential return content. It could specify the response format or units, but for most use cases it is complete enough to allow correct invocation.

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

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

The tool has zero parameters, so the schema is fully complete by definition. Baseline 4 applies because there is nothing to document; the description correctly avoids inventing unnecessary parameter details.

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

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

The description uses the specific verb 'Returns' and explicitly names the resources (gold, silver, platinum, palladium) plus the daily change percentages. This clearly distinguishes it from sibling tools like get_price_history, making the purpose immediately obvious.

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 should be used when current spot prices are needed, but it does not explicitly state when to use this instead of get_daily_brief or get_price_history. No alternatives or exclusions are mentioned, leaving usage context implicit.

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 provided, the description must disclose behavioral traits, but it only states the return content. It does not mention pagination behavior, read-only nature, response format, or any side effects. The schema's limit/offset parameters hint at pagination, but the description adds no behavioral context.

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

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

The description is one sentence, immediate and free of fluff. It front-loads the core function with 'Returns Stack Signal' and adds helpful nuance about the content source. It earns its place with no wasted words.

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

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

For a simple read tool with fully documented schema parameters, the description is minimally adequate. However, it lacks context about the return structure and fails to differentiate from other market intelligence tools. Given the sibling count, more contextual guidance 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?

The input schema already provides descriptions for all three parameters (limit, offset, category), achieving 100% coverage. The description adds no additional parameter semantics, leaving the schema to carry the full burden without extra 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?

The description clearly states the tool returns 'Stack Signal' market intelligence with commentary, using a specific resource name. It distinguishes this from sibling tools like get_daily_brief or get_speculation by referencing a uniquely named product. The verb 'Returns' is clear and direct.

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 offers no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or comparisons to sibling tools. An agent would have to infer from the name and description alone.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It lists output fields but omits any behavioral traits such as data freshness, access constraints, rate limits, or whether this is a read-only operation.

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 well-structured sentence that packs all key output fields without redundancy. Every word 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 one-optional-parameter read tool with no output schema, the description lists all returned fields and includes units (ounces). It is sufficiently complete, though it could mention data source or frequency if relevant.

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 fully documents the only parameter (metal) with an enum and description. The tool description adds no additional parameter meaning, but since schema coverage is 100%, 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?

Clearly states the tool returns COMEX warehouse inventory and enumerates specific data points (registered, eligible, combined ounces, daily changes, open interest, oversubscribed ratio). This is a specific verb+resource and distinguishes it from sibling data 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?

Implies usage when COMEX inventory data is needed, but provides no explicit when-to-use guidance or comparisons with sibling tools. No exclusions or alternatives 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?

There are no annotations, so the description must carry the full burden. The descriptor 'extract' indicates a read-like operation, but it does not disclose whether the tool only returns data or also saves it to the portfolio, nor does it mention any side effects or limitations. This is adequate but not deeply transparent.

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

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

The description is a single, focused sentence of 10 words. It is front-loaded with the core action ('Extract precious metals purchase data') and wastes no words. Perfectly concise.

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 (2 parameters, no output schema). The schema is thorough, and the description explains the core function. However, the lack of an output schema means the description should provide more detail on what the returned 'purchase data' looks like or any behavior caveats. The description is adequate but leaves some gaps.

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

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

The schema covers 100% of the parameters with descriptions for api_key and image_base64. The description adds no extra parameter-level meaning beyond mentioning 'receipt image' and 'AI vision,' so it meets the baseline for high schema coverage without enriching the semantics.

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

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

The description clearly states the tool's function: 'Extract precious metals purchase data from a receipt image using AI vision.' It uses a specific verb ('extract'), identifies the resource (receipt image), and specifies the method (AI vision). This clearly distinguishes it from sibling tools like add_holding or get_portfolio.

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 when to use the tool: when you have a receipt image containing precious metals purchase data. However, it does not explicitly mention alternatives or exclusions, such as manual entry via add_holding. This gives clear context but lacks explicit when-not-to-use guidance.

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