troystack

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

No annotations are provided, so the description must carry the full burden. It only states 'Add a precious metals purchase' which is the core action, but does not disclose side effects (e.g., appends to portfolio, whether duplicate purchases are allowed), auth requirements beyond the schema's api_key field, or result/return behavior. For a mutating tool, this is insufficient.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the verb and object concisely. Perfectly effective for its minimal length.

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?

With 7 parameters, no annotations, and no output schema, the description is too minimal. It does not mention what happens after a successful add (e.g., returns updated portfolio or new holding ID), potential errors (invalid API key, duplicate), or how this fits with other tools. A more complete description is needed for safe use.

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%, meaning all parameters (api_key, metal, quantity, weight_oz, purchase_price, etc.) have descriptions. The tool description adds minimal meaning beyond that, merely framing the context as a purchase. Baseline 3 is appropriate as the schema does the heavy lifting.

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 ('Add') and resource ('precious metals purchase to your portfolio'), clearly distinguishing it from sibling tools like 'get_portfolio' or 'scan_receipt'. The action and target are unambiguous.

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

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

The description implies use when manually adding a precious metals purchase, but provides no explicit guidance on when to use this vs. alternatives like 'scan_receipt' (which may also add holdings) or exclusions. It is clear enough for basic use but lacks explicit when/when-not 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 carries the full burden of behavioral disclosure. It reveals a key behavioral trait: that providing an api_key changes the nature of responses to be portfolio-aware, which is not evident from the schema alone. However, it does not mention rate limits, data handling, or what constitutes an invalid api_key, leaving some gaps for a tool without annotations.

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

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

The description is extremely concise and well-structured: two sentences front-load the primary purpose and then immediately clarify the optional parameter usage. Every word adds value, with no redundancy or filler.

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 essential aspects: what the tool does, what the user can ask about, and how the api_key modifies behavior. It does not detail the response format, but given the conversational nature and lack of complex nested objects, the guidance is adequate for an agent 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?

Although the schema already provides descriptions for both parameters (100% coverage), the tool description adds meaningful context by specifying the topics that can be asked about and explicitly explaining the functional impact of the api_key parameter (personalized vs. general). This goes beyond the schema's terse 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 function with a specific verb ('Ask') and resource ('Troy'), and identifies the domain (precious metals, markets, stack). It is easily distinguished from sibling tools that focus on data retrieval or portfolio actions, as this is the only conversational tool.

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

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

The description provides conditional guidance on when to include the api_key (for personalized portfolio-aware answers) versus omitting it (for general market analysis), which is helpful for parameter selection. However, it does not explicitly contrast this tool with sibling alternatives or state when not to use it, leaving usage context somewhat implied.

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 burden of disclosing behavior. It does disclose the key return metrics and the 'per metal' grouping, which is useful. However, it does not mention any authentication requirement (api_key is in the schema), data freshness, or whether this is a read-only operation, though 'get' implies safety. It adds some behavioral context but avoids any discussion of potential side effects or edge cases.

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—a single comma-separated list. It is front-loaded with the key output metrics and includes no unnecessary words. It is not a full sentence, but its brevity makes it easy to scan. A slight improvement would be adding a verb like 'Retrieves', but as is, it is appropriately sized.

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 one parameter and no output schema, the description provides a reasonable list of what the agent can expect. It clarifies the grouping by metal but does not explain the response structure, calculation methodology, or how it relates to other analytics tools. The absence of usage guidelines and output schema details leaves gaps in context, but it is still adequate for a simple getter.

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 (api_key) with 100% description coverage. The tool description adds no additional semantic meaning about the parameter, so the baseline score of 3 applies. The schema already fully documents what the api_key is and that it is required.

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 title 'Get Portfolio Analytics' and the description listing specific metrics (cost basis, average cost per oz, break-even price, unrealized P/L per metal) clearly indicate the tool retrieves portfolio analytics. It distinguishes itself from sibling tools like get_portfolio by focusing on these specific computed metrics rather than raw holdings. However, the description is a fragment without an explicit verb, relying on the title for 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?

The description provides no guidance on when to use this tool versus the many sibling tools (e.g., get_portfolio, get_daily_brief, get_stack_signal). It does not mention any exclusions or alternative use cases. An agent would have to infer its purpose from the listed metrics, but there is no explicit when-to-use or when-not-to-use information.

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 reveals that providing api_key changes the output from generic synthesis to personalized, but doesn't describe other behavior like read-only nature, response format, or error handling. That's a moderate 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 two sentences, front-loaded with purpose, and every word earns its place. No fluff.

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

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

For a tool with one optional parameter and no output schema, the description covers the essential usage and intent. It could mention what the brief contains, but that isn't necessary for 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 description adds meaning beyond the schema by explaining that api_key yields a personalized brief while omitting it yields the latest market synthesis. This clarifies the parameter's effect beyond the schema's 'for personalized brief (optional)'.

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 delivers 'Troy's daily market brief' and distinguishes it from sibling tools like get_stack_signal and get_analytics. The verb 'get' is implied and the resource is specific and named.

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 when to use an api_key ('for personalized brief') and when to omit it ('for the latest Stack Signal market synthesis'), giving clear context. It doesn't explicitly name alternative tools, but the usage conditions are well-specified.

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 present, and the description provides minimal behavioral context. It does not disclose whether the calculation uses current spot prices, how the output is formatted, or any limitations. This is a significant gap for an unannotated 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 sentence with no fluff, making it efficient and front-loaded. However, it is terse to the point of omitting important details, but that is a completeness issue rather than a conciseness issue.

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?

Without an output schema or annotations, the description does not explain what the tool returns (e.g., total melt value in dollars) or whether it uses real-time spot prices. The parameter schema is complete, but the tool's behavior is under-specified.

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 documents all six parameters with coin types and silver content (100% coverage). The description adds no additional parameter semantics, so it relies on the schema's adequate 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 calculates silver melt value for pre-1965 US coinage, with a specific verb and resource. It distinguishes from sibling tools, though the inclusion of Kennedy 40% halves (1965-1970) and war nickels makes the 'pre-1965' label slightly inaccurate.

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

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

No explicit usage guidance or alternatives are provided. The use case is implied by the name and description, but there is no statement about when to prefer this over other get_* 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. The verb 'Returns' clearly indicates a read-only operation with no side effects, which is sufficient for this simple tool. It does not discuss rate limits, data freshness, or error conditions, but those are not critical for a portfolio fetch.

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 entire description is a single, front-loaded sentence that conveys the tool's purpose without any filler. It efficiently lists all major output categories.

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 compensates by enumerating the return contents (total value, cost basis, gain/loss, per-metal breakdown, individual holdings). This sufficiently outlines the response structure for an agent, though it omits format specifics like JSON or units.

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 already describes the only parameter (api_key) with 100% coverage, so the description adds no additional parameter semantics. 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 uses the specific verb 'Returns' and identifies the resource as 'your precious metals portfolio,' listing exact components (total value, cost basis, gain/loss, per-metal breakdown, individual holdings). This clearly distinguishes it from sibling tools like get_spot_prices or get_analytics.

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 use when portfolio data is needed, listing the exact data returned. However, it does not explicitly exclude alternatives or provide when-not-to-use guidance relative to the listed sibling tools, so it lacks explicit alternative comparison.

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. It describes the tool as returning data, which implies a read-only operation, but does not explicitly state this, nor does it mention authentication, rate limits, or response structure. The description adds minimal behavioral context beyond what the name and schema suggest.

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 with no redundant words. It conveys the essential purpose without unnecessary detail.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description provides the basic purpose but does not describe the return format or any quirks. For a price history tool, it would be helpful to know if the data is a list of points, but the absence of an output schema makes this somewhat 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?

The schema already documents both parameters (metal and range) with descriptions and enums, covering 100% of parameters. The description references 'precious metal' and 'time range' but does not add information beyond the schema, so a 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 provides historical spot price data for precious metals over a time range, aligning with the name and distinguishing it from current-price tools like get_spot_prices. It lacks an explicit verb but is specific enough to understand the resource and scope.

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

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

The description implies the intended use for historical price queries but does not explicitly state when to prefer it over alternatives such as get_spot_prices or get_analytics. No 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 does not explicitly state that the tool is read-only, what it returns, or any potential side effects. The verb 'calculates' implies a safe computation, but this is not confirmed, and there is no mention of output structure or error behavior.

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 that front-loads the verb and clearly states the purpose. It contains no unnecessary words 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?

The tool has four optional parameters and no output schema. The description does not explain what the multipliers look like, how they are returned, or the behavior when only some parameters are provided. This leaves significant ambiguity for an agent attempting to use the tool correctly.

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

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

The schema description coverage is 100%, with each parameter described as a target price. The description does not add meaning beyond the schema; it only restates 'hypothetical target prices' which is already in the schema. The baseline of 3 is appropriate since the schema handles the parameter 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 uses the specific verb 'calculates' and clearly identifies the resource ('price multipliers') and scope ('comparing current spot to hypothetical target prices'). This distinguishes it from siblings like get_spot_prices, which return current prices, and get_price_history, which returns historical 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 usage for hypothetical price scenarios but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. There is no clear 'when-to-use' guidance beyond the implied context of the what-if scenario.

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 burden of disclosing behavior. It clearly indicates a read-only operation by using 'returns,' but does not add details like currency, data source, or rate limits. However, for a simple getter, it is sufficiently 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 concise sentence that front-loads the action ('Returns current spot prices') and lists the specific metals and derived metric. 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 no-parameter tool with no output schema, the description adequately explains what is returned (spot prices for four metals, daily change percentages). It omits units or currency, but the simplicity of the tool makes this acceptable.

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 zero parameters, so the baseline is 4. The description correctly does not need to explain parameter semantics since there are none to document.

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 current spot prices for a specific list of metals (gold, silver, platinum, palladium) and includes daily change percentages. This is a specific verb+resource combination that distinguishes it from sibling tools like get_price_history.

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 obtaining current spot prices, but does not explicitly mention when to avoid using it or name alternatives like get_price_history for historical data. The context is clear but lacks explicit 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Returns' which implies a read-only operation, but it does not mention response format, pagination, whether it returns a list or single item, authentication needs, or any side effects. For a tool with no output schema, this lack of return-structure detail is a significant 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 single sentence that front-loads the main action ('Returns Stack Signal') and adds a concise explanatory clause in the em-dash. There is no fluff or redundancy. It is appropriately sized and easy to parse.

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

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

With 3 optional parameters, no output schema, and no annotations, the description should clarify the return structure and behavior. It only vaguely indicates the content ('market intelligence with commentary') but doesn't explain whether the response is a list, how pagination works, or what fields are included. This leaves the agent uncertain about how to handle the result, especially without an output schema.

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

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

The input schema covers 100% of parameters with individual descriptions for limit, offset, and category, so the baseline is 3. The tool description does not add any parameter context, but it is not necessary given the complete schema. The description also doesn't mention defaults, but those are documented in the schema.

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

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

The description clearly states the tool returns 'Stack Signal' and describes it as curated precious metals market intelligence with commentary. This specifies the verb and resource clearly, though it does not explicitly differentiate from sibling tools like get_daily_brief or get_speculation, which might also return market-related content. The title and name reinforce the resource.

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 does not provide any guidance on when to use this tool versus alternatives. There are no stated conditions, prerequisites, or exclusions. Without mentioning sibling tools or contextual cues, the agent receives no help in deciding between this and similar retrieval tools like get_daily_brief.

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 does not disclose any behavioral traits beyond the read-like verb 'Returns' – no mention of data frequency, safety profile, rate limits, or side effects. The schema's note about the optional metal filter is helpful but lives in the schema, not 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?

A single, information-dense sentence that front-loads the action and resource, followed by a concise list of returned fields. Every word earns its place; no redundancy.

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

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

For a simple read-only tool with one optional parameter, the description plus fully covered input schema provide a functionally complete picture. The description lists all output fields, which partially compensates for the lack of an output schema. However, it omits usage context and data characteristics, keeping it from being outstanding.

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 single optional metal parameter with an enum and clear description of default behavior, so the description adds no additional parameter semantics. Baseline 3 applies due to full schema coverage.

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

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

The description uses a specific verb 'Returns' with a clear resource 'COMEX warehouse inventory' and enumerates the exact metrics (registered, eligible, combined ounces, daily changes, open interest, oversubscribed ratio). This makes it unambiguous and easily distinguishable from sibling price/analytics 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 no guidance on when to use this tool versus other get_* tools. It simply states what it returns, with no scenarios, prerequisites, or references to 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 are provided, so the description must carry the full burden. It only states what the tool does ('extract...using AI vision') without disclosing whether it has side effects, the return format, or any limitations. This is a significant 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 single sentence with the key verb and object front-loaded. Every word earns its place; no unnecessary details 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?

With no output schema and no annotations, the description is incomplete for an agent. It does not specify what the tool returns, error behavior, or whether it creates a holding. This leaves critical information missing for a 2-param 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 description coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already states (e.g., it doesn't elaborate on api_key or image_base64 format constraints).

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 ('Extract') and identifies the resource ('precious metals purchase data' from a receipt image). 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 clearly implies the use case: when you have a receipt image containing precious metals purchase data. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.

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