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

Annotations show readOnlyHint=false, destructiveHint=false, so description carries limited burden. Adds that it 'enables year to close' but doesn't elaborate on side effects, reversibility, or permissions. Adequate 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?

Two sentences, front-loaded with purpose and condition. No wasted words.

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

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

No output schema, but description sufficiently covers when and why to use. Minor omission: no mention of return value or confirmation, but acceptable for a simple action 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 schema already describes all 4 parameters. Description does not add extra meaning beyond the schema, meeting baseline.

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

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

Title and description clearly state verb (attest/sign off), resource (bank account for financial year), and condition (out of scope). Distinguishes from siblings like reconcile_financial_year or close_financial_year by specifying a specific scenario.

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 for accounts with no statement to reconcile against,' providing clear when-to-use guidance. Implicitly excludes tools that require statements.

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

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

Annotations indicate write (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that this is a direct write (not a proposal), marks the cash row as matched, and that income is counted exactly once. It also mentions that the action can be undone via the app's 'Detach' feature, providing valuable behavioral context beyond the annotations.

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

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

The description is well-structured: it starts with the main purpose, then details the effect, distinguishes from alternatives, provides prerequisites, and ends with an undo note. While it is somewhat lengthy, every sentence adds relevant information, and it is front-loaded with the core action.

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

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

Given the tool's complexity (11 parameters, 3 required) and no output schema, the description covers essential context: what the tool does, how to prepare (find unmatched cash transactions), how to identify the holding, and what to do if wrong. It does not discuss return values, but that is acceptable 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?

Schema description coverage is 91%, so most parameters are already described. The description adds context for a few key parameters (e.g., 'ticker preferred', 'franking_credits for franked dividends'), but this is minimal additional value. Overall, the description does not significantly enhance understanding beyond the schema.

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

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

The description uses a specific verb ('Link') and specifies the exact resource ('income credit on a bank account' to 'the holding that earned it'). It clearly distinguishes the tool's function from record_income by stating it is a direct write, not a Review-Queue proposal, and explains the effect on the new security transaction and cash row.

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

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

The description explicitly states when to use this tool ('cash has already arrived'), when not to use it (if you want a review proposal, use record_income), and provides a method to find candidates using list_cash_transactions with specific match_status and category filters. It also advises on how to identify the holding (ticker preferred) and mentions the undo process if needed.

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

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

Discloses the locking behavior ('locks all dated rows') and error behavior ('returns an error explaining what's unresolved') beyond annotations, which only indicate non-read-only and non-destructive.

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 fluff: first states action, second states precondition and error, third recommends prerequisite. 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?

Complete coverage: preconditions, behavior, error handling, and parameter sources. No output schema needed; description suffices for correct tool 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?

Adds meaningful context to parameters: fund_id discovery via whoami or list_funds, financial_year format as label or numeric id from list_financial_years. Schema coverage is 100%, but description enhances usability.

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: 'Close a financial year — locks all dated rows in that year against further edits.' This verb-resource combination is specific and distinguishes it from siblings like reopen_financial_year.

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

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

Explicitly states when to use ('Only works once the year is reconciled') and what to do first ('Run reconcile_financial_year first'). Provides clear guidance on prerequisites and error handling.

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

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

Annotations indicate write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). Description aligns by stating 'Create...' and notes return behavior ('Returns the new account with its id'). Adds context about currency (AUD-only) and default opening balance, but does not contradict annotations.

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

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

Four sentences with no wasted words. Front-loaded with verb and resource, followed by usage case, prerequisite check, and follow-up. Efficient and well-structured.

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

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

Given 11 parameters and no output schema, the description provides essential behavioral context: return value (id), currency limitation, default opening balance, and workflow steps. Slightly incomplete as it doesn't explain all parameters, but overall adequate for an experienced user.

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 91%, so parameters are well-documented. Description adds overall context but does not significantly enhance per-parameter understanding beyond what schema already provides. 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?

Tool description clearly states it creates a new cash/bank account under a fund for tracking and reconciling. It provides examples (nabtrade cash hub, term deposit, operating account) and distinguishes from sibling tools like list_bank_accounts and record_cash_transaction by mentioning them in context.

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

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

Explicitly states when to use ('when a statement or CSV belongs to an account the fund doesn't have yet') and advises checking list_bank_accounts first to avoid duplicates. Also recommends following up with record_cash_transaction to load movements, providing a clear workflow.

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

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

Annotations indicate a non-destructive write; the description adds that this writes the holding directly while the buy transaction should still go through record_trade for review, providing full context beyond annotations.

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

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

Two sentences plus a note, front-loaded with purpose and usage, 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?

Covers purpose, usage, behavioral notes, and workflow integration. Missing explicit mention of return value, but given standard creation tools, this is 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?

Schema coverage is 91% with good descriptions for each parameter; the description adds minimal new semantics but reinforces usage context. 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 creates a new holding (security/asset) under the specific condition of a previously unheld security, distinguishing it from sibling tools like record_trade.

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 tells when to use (only for never-before-held securities) and provides an alternative tool (record_trade) for existing holdings, along with a prerequisite to check list_holdings first.

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 discloses key behaviors: idempotency, that it returns the existing return if one already exists, and that it returns auto-filled figures and gaps. This adds value beyond the annotations (readOnlyHint=false, destructiveHint=false), providing clear understanding of the tool's effect.

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: two sentences that efficiently convey the core purpose, idempotency, and return value. No unnecessary words, and the key information is 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 tool has only two parameters, no output schema, and minimal annotations, the description provides sufficient context: it explains what the tool does, its idempotent nature, and what it returns. It could potentially elaborate on the 'auto-filled figures and gaps', but overall it is complete for an agent to understand 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?

The input schema has 100% coverage with descriptions for both parameters (fund_id and financial_year). The description does not add additional meaning beyond what the schema already provides, 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 opens or resumes an SMSF annual return for a fund and financial year. It specifies the verb 'Open (or resume)' and the resource 'SMSF annual return', and implicitly distinguishes from siblings like 'get_smsf_return' by implying this is for creation/resumption.

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 mentions idempotency and returning existing returns, which gives some context for usage, but it does not explicitly state when to use this tool versus alternatives like 'get_smsf_return' or 'update_smsf_return_field'. No when-not or alternative guidance is 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?

Annotations provide destructiveHint=true; description adds detail that it discards security transaction and returns bank credit to unmatched pool, and specifies that it only works on user-attributed rows (match_status 'matched'). No contradiction.

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

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

Two sentences: first explains action and effect, second specifies usage and limitations. No extraneous words, front-loaded with key 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?

Covers all necessary aspects: purpose, prerequisites (user-attributed rows), error conditions, relationship with sibling tool, and intended workflow. No output schema needed for this tool type.

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

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

Schema coverage is 100% with descriptions. Description adds usage context for each parameter (e.g., cash_transaction_id must have match_status 'matched'), which helps beyond 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?

Explicitly states verb 'detach' on resource 'cash transaction' and context of undoing an attribution. Differentiates from sibling tools like attribute_cash_transaction and unreconcile_cash_transaction by specifying its unique role.

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?

States when to use (wrong holding/details), when not to use (auto-matched feed rows), and provides follow-up action (detach then attribute_cash_transaction again). Includes explicit error condition for unattributed rows.

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

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

The description adds value beyond the readOnlyHint annotation by explaining that extraction runs in the background and that polling is needed when status is 'processing'. No contradictions with annotations.

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

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

The description is concise with three sentences, each serving a clear purpose: stating what the tool does, when to use it, and the asynchronous behavior. 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 absence of an output schema, the description covers the key aspects (returned fields, polling behavior). It does not mention error handling or edge cases, but for this simple tool it is mostly complete.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add extra meaning beyond the 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?

The description uses a specific verb 'Fetch' and explicitly mentions the resource 'uploaded document including its extracted statement lines' with match_status. It clearly distinguishes from siblings like upload_document and list_documents.

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 advises using this tool after upload_document to check extraction status and reconciliation results, and to poll if status is 'processing'. It provides clear context but does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds value by detailing the specific metrics returned and noting amounts are in AUD. It does not contradict annotations and is transparent about the analysis scope.

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

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

Two sentences, front-loaded with key metrics, concise and structured. Every sentence adds value.

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

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

Given the tool's complexity (multiple metrics), no output schema, and annotations, the description is complete: it lists all output categories and usage context. No gaps.

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

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

Schema coverage is 100%, so parameters are well-documented. The description does not add new parameter-specific meaning beyond the schema, so 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 clearly states it provides 'deep analysis of a single holding' with a specific list of metrics (true return, annualised return, income totals, costs, CGT info). This distinguishes it from sibling tools like list_holdings 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?

Explicitly says 'Use when asked how a specific investment has really performed, or about the tax impact of selling.' This gives clear context, though it does not exhaustively list when not to use it.

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

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

Annotations already declare readOnlyHint=true. The description adds that amounts are in AUD and lists output fields, but does not reveal additional behavioral traits like rate limits or idempotency. This meets the baseline for a read-only tool with annotations.

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

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

Three sentences, no wasted words. Front-loaded with purpose, then content details, then use case. Structurally ideal for quick scanning.

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 one parameter and no output schema, the description sufficiently explains the return value (fund summary, allocations, holdings). It covers key use cases and output contents, though it does not mention pagination or limits (likely not needed).

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

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

Schema covers fund_id with 100% description. The description adds value by suggesting how to discover fund_id via 'whoami or list_funds', providing practical guidance beyond the schema.

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

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

The description clearly states it provides a 'Full portfolio snapshot' including fund summary, asset allocation, and active holdings. It distinguishes from sibling tools like list_holdings or get_holding_analysis by emphasizing this is a single comprehensive call for a top-level view.

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 answers when to use it: 'to answer 'how is the fund doing?' or 'what do we hold?'. While it doesn't explicitly list alternatives, the context implies this is the best high-level entry point among many granular 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?

Annotations already declare readOnlyHint=true, and the description adds value by detailing what the tool returns (fields, per-member statements, gap register) and noting the auto-fill behavior. No contradictions.

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

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

The description is three sentences, each serving a distinct purpose: what it fetches, how to use it, and extra context. It is front-loaded and concise with no superfluous 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 tool's simplicity (read-only, two parameters, no output schema), the description fully covers the return content and lifecycle. It explains what is retrieved and how it fits into the workflow with related tools.

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

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

Schema description coverage is 100%, with property descriptions already explaining the origin of fund_id and smsf_return_id. The description reiterates usage but adds no new semantic meaning beyond the schema.

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

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

The description clearly specifies that the tool fetches an SMSF annual return with detailed components: every section and field with ATO labels, computed values, statuses, per-member statements, and the gap register. It distinguishes itself from sibling tools like list_smsf_return_gaps or create_smsf_return.

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 advises to pass smsf_return_id from list output or create one first, providing clear usage context. It also mentions that figures auto-fill from the ledger and can be edited via update_smsf_return_field, guiding the agent on related actions. It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already declare readOnlyHint=true, and the description adds context by detailing the output fields (name, category, dividends, etc.) beyond the schema. No behavioral contradictions; the description aligns with the read-only nature.

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 with no wasted words, front-loading the purpose and then providing usage guidance. It 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?

Given the tool's simplicity (no parameters, no output schema), the description completely covers what it does and what it returns, making it sufficient for an AI agent to understand and invoke correctly.

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

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

With zero parameters and 100% schema coverage, the baseline is 4. The description adds no parameter info, which is appropriate since none exist.

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 lists asset types supported by Beeswax Shares, specifying the fields returned (name, category, tickers, dividends, franking credits) and its use in selecting a valid asset_type for create_holding. This distinguishes it from sibling tools dealing with other entities.

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

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

The description explicitly says to use this tool to pick a valid asset_type for create_holding or to understand the fund's asset allocation categories, providing clear context. However, it does not mention when not to use it, though no alternative tool exists for this purpose.

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 annotations include readOnlyHint: true, confirming the tool is read-only. The description adds behavioral detail by listing the returned fields and currency. No contradictions; the description complements annotations well.

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

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

The description is two sentences: the first states functionality and output fields, the second gives usage guidance. No redundant information; every sentence is essential.

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 fully covers what it does, what it returns, when to use it, and currency. No gaps.

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

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

Schema coverage is 100% with one parameter (fund_id) already documented. The description implies the context (SMSF) but does not add new parameter-level meaning beyond the schema. 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 clearly states the tool lists bank accounts with specific fields (current balance, opening balance, role, feed status). It uses a specific verb ('list') and resource ('SMSF's bank accounts'), distinguishing it from siblings like 'attest_account' or 'create_bank_account'.

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

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

The description explicitly states when to use this tool: to find a bank_account_id before using list_cash_transactions or record_cash_transaction, or to see cash on hand. It also includes the note that all amounts are in AUD, providing clear context for use.

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

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

Annotations already declare readOnlyHint=true. Description adds that it returns broker IDs and CHESS sponsorship info, but no deeper behavioral disclosure (e.g., pagination, data freshness).

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

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

Two efficient sentences. First defines function, second provides guidance. No redundant or 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?

For a simple list tool with no parameters and no output schema, the description covers what it returns and when to use it. Complete for the tool's 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?

No parameters in schema; schema coverage is 100%. Baseline 4 applies as description does not need to add parameter info. Description usefully hints at output content (broker IDs, CHESS info).

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 lists brokers with IDs and CHESS sponsorship info. Distinguishes from siblings by specifying use case before create_holding or interpreting references.

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

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

Explicitly states when to use: to find broker_id before create_holding or interpret broker references. Provides clear context but does not list alternative tools for similar tasks.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds behavioral details: 'newest-first', paginated, signed amounts (+/-), and currency (AUD). These go beyond the annotations and provide helpful context without contradiction.

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

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

Four sentences, all essential: purpose, filters, usage, and behavioral note. No fluff. Front-loaded with the key verb and resource. Every sentence 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?

Given 9 parameters and no output schema, the description covers purpose, usage, filters, ordering, and signed amounts. It lacks details like pagination metadata in response, but schema handles page/per_page. Overall, it provides sufficient context for an agent 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?

Schema coverage is 100%, so all parameters have descriptions. The description does not add significant meaning beyond the schema, except for mentioning ordering ('newest-first') which is not in parameters. Baseline is 3, and the description meets that without substantial improvement.

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 lists cash-ledger movements on a bank account, specifying types (deposits, withdrawals, etc.) and ordering (newest-first, paginated). This distinguishes it from sibling tools like record_cash_transaction or update_cash_transaction, which are mutation operations.

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 usage contexts: 'review cash flow, check whether a movement was already recorded, or find uncategorised/unmatched items.' It does not explicitly state when not to use the tool or mention alternatives, but the context is sufficiently clear.

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

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

Annotations declare readOnlyHint=true; description adds ordering ('newest first') and content context ('extraction status and reconciliation summaries'). No contradiction, but could mention pagination behavior explicitly.

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: first delivers core functionality and output details, second provides use cases. No fluff, front-loaded with essential information.

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

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

For a list tool with no output schema, it describes output ordering and content. Input schema covers parameters. Could be more explicit about pagination, but adequate given simplicity.

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

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

Schema has 100% coverage for all four parameters. Description adds no parameter-specific details, but the baseline is 3. The mention of 'extraction status' hints at the status filter, providing minimal extra value.

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 clearly states verb 'list', resource 'uploaded documents', and specifies order 'newest first' with 'extraction status and reconciliation summaries'. It provides two specific use cases, differentiating it from sibling tools like get_document.

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 mentions when to use: to check for duplicates before upload and to find a document ID. It does not explicitly exclude other scenarios, but the guidance is clear and practical.

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

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

Discloses that the tool is read-only (consistent with readOnlyHint=true) and lists the output includes status (open/closed/lodged) and dates. No contradictions with annotations; adds behavioral context beyond the annotation.

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 with no wasted words: first states the action and output, second gives usage guidance. Perfectly front-loaded and to the point.

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 still mentions output fields (status, dates) and the parameter is well-documented in schema. Lacks details on edge cases (e.g., no financial years) but sufficient for a simple list 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 has 100% description coverage for the single parameter fund_id, which already explains its purpose. The description adds no additional semantics beyond the 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?

Clearly states it lists financial years for a fund, including status and dates, and explicitly distinguishes from sibling tools like close_financial_year or lodge_financial_year by noting its use to find the year label.

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 to find the year label to reconcile, close or lodge', providing clear context for when to use this tool. Lacks explicit exclusions or alternatives but is sufficient given the sibling 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?

Annotations declare readOnlyHint=true, and the description aligns by describing a read-only listing. It adds valuable context about the specific fields returned, with no contradictions or missing disclosures about side effects.

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

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

Three concise sentences: first states purpose and output fields, second provides usage context, third offers alternative. No redundant words, front-loaded with essential information.

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

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

For a list tool with no output schema, the description adequately lists the returned fields and provides usage guidance. It lacks details like ordering or defaults, but given the tool's simplicity and high schema coverage, it is nearly complete.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (page, per_page). The description adds no additional parameter meaning beyond what the schema already provides, resulting in a baseline score of 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?

Description clearly states the verb 'list' and resource 'your SMSF funds', enumerates the specific headline figures returned, and distinguishes from the sibling tool 'whoami' for simpler needs. This meets all criteria for a 5.

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

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

Explicitly instructs when to use ('when you need fund-level numbers') and when to use an alternative ('use whoami if you only need fund IDs'), providing clear decision guidance for the agent.

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

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

Annotations declare readOnlyHint=true, and the description confirms a read-only listing operation. It adds value by stating returns include valuation and gain/loss per holding, beyond what annotations provide.

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

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

Three sentences, front-loaded with the main action, no redundant information. Each sentence 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?

With no output schema, the description explains return content (valuation and gain/loss). It covers key use cases. Could mention pagination but schema already provides that info.

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. Description mentions filters but adds minimal extra meaning beyond what each parameter's schema description already conveys.

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

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

The description clearly states it lists holdings in a fund with filters, and differentiates from sibling tools by mentioning specific use cases like finding a holding's ID before record_cost or update_price.

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

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

Explicitly states when to use: to find a holding's ID by ticker/name before record_cost/update_price, or to review holdings by status. Provides clear context for alternative 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?

Annotations provide readOnlyHint=true, and the description adds behavioral detail about output tags (blocking vs advisory) and the types of gaps reported. This goes beyond the annotation, though no side effects are needed. The description adds meaningful 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?

Two sentences: first defines purpose and examples, second states output usage. No redundant words or sentences. Every sentence 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 list tool with annotations indicating read-only, the description covers what the tool returns (gaps with tags) and when to use it. No output schema is provided, but the description offers enough context for an agent. Minor gap: no explicit mention of return structure beyond tags.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the blocking_only parameter's effect ('tagged blocking or advisory'), but does not significantly enhance understanding beyond the schema. 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 a specific verb ('List') and resource ('SMSF return gaps') with concrete examples (missing franking credits, EOFY valuations, etc.). The title matches and there is no sibling tool with similar name, making it clearly distinguishable.

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 'Use to see what to fix before confirming sections or finalising,' providing clear usage context. It does not explicitly mention when not to use or list alternatives, but the sibling tools are all different actions, so the guidance is sufficient.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, so the tool is a non-destructive mutation. The description adds context that it marks the year as lodged with the ATO, which is a state change but not destructive. It doesn't contradict annotations, and provides additional context about the action's place in the workflow.

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, uses active voice, and is front-loaded with the core action. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (2 required params, no output schema), the description fully covers the purpose, prerequisites, and when to use. It references sibling tools for context and provides parameter sourcing tips, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100% with both parameters described. The description adds valuable sourcing guidance: 'discover via whoami or list_funds' for fund_id and 'the label "2023-24" or its numeric id (from list_financial_years)' for financial_year. This significantly helps the agent obtain correct values.

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 'Mark' and resource 'financial year as lodged with the ATO'. It specifies the precondition ('Only works on a closed year') and the workflow order ('Use after the SMSF annual return has been submitted'), distinguishing it from siblings like close_financial_year or unlodge_financial_year.

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: after the SMSF annual return has been submitted, and only on a closed financial year. It implies when not to use (if the year is not closed or return not submitted), providing clear 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?

Discloses that it writes immediately and will be rejected if the financial year is closed, adding value beyond annotations (which only give hints). Does not mention idempotency or error behavior for already-reconciled transactions, but provides key operational traits.

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 with no superfluous content. The most critical information (purpose, write behavior, rejection condition) is front-loaded and 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?

Covers essential purpose and constraints but lacks details on return values, error handling, or behavior if already reconciled. Given no output schema and low complexity, the description is adequate but could be more complete.

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

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

Schema coverage is 100% with each parameter described. The description adds no additional parameter-level meaning, 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?

The description clearly states it reconciles a single cash transaction by setting the line-level reconciled flag, using specific verb and resource. It distinguishes from siblings like 'reconcile_financial_year' and 'run_account_reconciliation' by focusing on a single row.

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?

Gives context for when to use (before year closure) and a rejection condition, but does not explicitly compare to alternative reconciliation tools or state when not to use. Lacks explicit differentiation from batch reconciliation 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, so it's a safe mutation. The description adds behavioral context by stating the tool returns refreshed line match statuses and a summary, and that it re-runs reconciliation, which implies state changes. No contradictions.

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

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

Two sentences cover purpose, return value, and usage context without redundancy. Every sentence earns its place, and the information is 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?

For a tool with 2 well-documented parameters and no output schema, the description adequately explains the return value (refreshed line match statuses and summary categories) and usage triggers. It is complete enough for effective 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 coverage is 100% with descriptions for both parameters. The description adds value by suggesting discovery methods for fund_id ('via whoami or list_funds') and clarifying document_id's purpose, going beyond the schema alone.

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

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

The description clearly states the verb 're-run reconciliation' and identifies the specific resource: a document's extracted statement lines against the fund's ledger. It distinguishes itself from sibling tools like reconcile_cash_transaction and reconcile_financial_year by focusing on document-level reconciliation.

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

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

The description explicitly states when to use the tool: after ledger changes (e.g., proposals approved) or when re-checking a statement. While it doesn't list exclusions or alternatives, the context is clear and actionable.

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

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

Annotations indicate it is not read-only and not destructive, but the description does not disclose side effects like updating reconciliation status or what data changes. Only mentions outputs.

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

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

Concise, with purpose front-loaded. The prerequisite is included efficiently. Could be slightly more structured but overall 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?

Covers the main process and expected outputs, plus a critical prerequisite. Lacks detailed handling of edge cases but adequate for a reconciliation tool.

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

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

Schema already covers both parameters with good descriptions; the tool description adds no extra meaning beyond the schema.

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

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

Clearly states the tool reconciles a financial year by matching cash and computing balance proofs. However, it does not explicitly differentiate from siblings like run_account_reconciliation.

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

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

Provides a useful prerequisite: record statement balances first. But lacks guidance on when not to use or when to prefer alternative 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?

Describes write behavior to cash ledger as low-risk record-keeping, mentions idempotency via external_ref. Annotations already note it's not read-only or destructive, so added context about idempotency and ledger impact is valuable.

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 paragraph covers all key aspects without fluff. Could be slightly more structured but remains efficient and focused.

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 12 parameters and no output schema, description addresses usage context, parameter semantics, and behavioral notes. Idempotency and category-specific requirements are well covered. Missing output description is acceptable given schema coverage.

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

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

With 92% schema coverage, description adds meaning beyond schema: amount is signed, external_ref as idempotency key, fund_member_id required for certain categories. This aids correct usage.

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

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

Clearly states it records cash movements on a bank account, listing specific categories and distinguishing from feed-sourced rows. Sibling tools like record_cost are referenced, showing differentiation.

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

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

Explicitly says when to use: accounts with no live bank feed or one-off entries. Contrasts with automatic feed-sourced rows and mentions similar tool record_cost. Also notes required context for contributions/benefits.

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 show readOnlyHint=false and destructiveHint=false. Description adds value by stating 'Writes directly to the holding's cost ledger' (confirming write operation) and characterizes costs as 'low-risk records'. Explains that tax_deductible feeds true-return and tax calculations. No contradictions with annotations.

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

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

Three sentences, front-loaded with purpose and examples. Every sentence adds unique value: purpose/examples, behavioral context (direct ledger, risk), and tax impact. 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?

Given 8 parameters, 5 required, high schema coverage, and no output schema, the description covers the essentials: purpose, examples, ledger behavior, low-risk nature, and tax implication. Could mention that the record is immediately persisted, but overall complete for its 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?

Schema coverage is 88%, so baseline is 3. Description adds meaning by reinforcing 'Amounts in AUD' and explaining that tax_deductible feeds fund calculations. Provides examples for cost_type. Adds context beyond schema without duplicating 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?

Description clearly states the tool records a holding-level cost/expense for SMSF, with specific examples (property rates, insurance, management fees). It explicitly distinguishes from sibling tools like record_income and record_trade by noting costs go directly to the ledger while others use proposals.

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

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

Provides clear context on when to use (holding-level costs) and contrasts with trades/income that use proposals. Mentions tax_deductible affects calculations. Does not explicitly name alternative tools or state when not to use, but the contrast is sufficient.

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?

Describes that the tool writes immediately with no review step, and mentions idempotency behavior via external_ref. This adds value beyond annotations (readOnlyHint=false, destructiveHint=false). No contradictions.

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

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

Five sentences, front-loaded with core purpose. Every sentence adds distinct value. No fluff 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?

Given high schema coverage and no output schema, the description covers use cases, parameter guidance, and behavioral aspects comprehensively. All required context for an agent to use the tool correctly is present.

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 92%, so baseline is 3. Description adds meaning for ticker vs holding_id, franking credits importance, external_ref purpose, reasoning for audit trail, and default currency. Provides good supplemental 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?

Description clearly states it records income events (dividend, distribution, interest, rental income) to an SMSF ledger, distinguishing it from sibling tools like record_cost or record_trade. It specifies the resource and 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?

Explicitly states when to use: for dividend statements, distribution advice, or rent receipts. Provides guidance on identifying holdings, including franking credits, using external_ref for idempotency, and adding reasoning for audit trail.

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 discloses mutability ('record or correct', 're-recording updates it'), consistent with destructiveHint=true. It adds context about idempotency per date, which is valuable beyond the annotation. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose and constraints. Every sentence adds value. No redundant or vague language.

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 4 required parameters and no output schema, the description covers purpose, usage, idempotency, and currency. It does not mention response format or failure cases, but the annotations provide destructiveHint. Slightly incomplete for a mutation tool, but adequate.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description adds high-level context: 'Amounts in AUD' for current_balance, and 'statement's closing balance and closing date' mapping to parameters. This adds value beyond the schema.

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

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

The description clearly states the verb 'Record (or correct)' and the resource 'bank statement's closing balance as at a date'. It specifies a key constraint: one snapshot per date with update semantics. This distinguishes it from sibling tools like reconcile_financial_year or record_cash_transaction.

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 for when to use: for year-end balance reconciliation, using the statement's closing balance and date. It implicitly advises against alternatives by stating the specific purpose, but does not explicitly list when not to use or compare to 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?

The description discloses the tool writes immediately with no review step, aligning with annotations (readOnlyHint=false, destructiveHint=false). It also explains idempotency via external_ref, currency default (AUD), and audit trail for reasoning. No contradictions with annotations.

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

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

The description is well-structured with clear instructions in separate sentences. Each sentence adds value, though it could be slightly more concise without losing 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 description covers all necessary aspects for a trade recording tool: when to use, prerequisites, parameters, behavioral traits. However, it does not explicitly mention the return value/output, which is a minor gap given no 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?

Schema coverage is high (92%), and the description adds meaningful context beyond the schema: identifying holding by ticker or holding_id, mandatory external_ref when source has stable ID, reasoning for audit trail, and currency default (AUD). This adds value for parameter usage.

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 records a buy or sell trade to the SMSF ledger, with specific verb ('Record') and resource ('trade'). It distinguishes from sibling tools like record_cash_transaction, record_cost, record_income, which cover different financial events.

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

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

The description explicitly states when to use (trade found in email/contract note/conversation) and when to use a precursor (use create_holding first if holding doesn't exist). It also provides guidance on passing external_ref for idempotency and reasoning for audit trail.

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

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

Annotations indicate non-read-only and non-destructive. Description adds that it unlocks rows for edits, but could elaborate on other effects like reverting reconciliations. Still good 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?

Two sentences, front-loaded with the main action, no unnecessary words. Highly efficient.

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

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

Despite no output schema, the description fully covers usage constraints and integrates well with sibling tools. No gaps for this simple state-change tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add extra info beyond the 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?

The description clearly states the verb 'reopen' and the resource 'financial year', and distinguishes it from siblings like close_financial_year and lodge_financial_year.

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 'Only works on a closed year' and provides the alternative 'to revert a lodged year use unlodge_financial_year first', guiding correct tool selection.

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

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

Annotations already declare non-readOnly and non-destructive. Description details the matching actions but doesn't clarify if records are modified or only linked. Some behavioral gaps remain.

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 tight sentences: first covers purpose, second covers usage. Every word adds value and is 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?

Describes return value (match summary) and process. Lacks differentiation from sibling reconciliation tools but is otherwise complete for a batch operation.

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 detailed descriptions. The tool description adds no extra semantic value beyond the schema, meeting the baseline.

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

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

The description clearly states the tool's function: running cash matcher over unmatched feed rows to link, pair, and categorize. It distinguishes from sibling tools like reconcile_cash_transaction by describing a batch process.

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 after recording trades/income' which gives clear timing context. Lacks explicit when-not-to-use or alternatives, but the context is sufficient.

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

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

Annotations declare readOnlyHint=true; the description adds that results are sorted newest-first and paginated. It does not disclose potential rate limits or data volume implications, but the read-only nature is well conveyed.

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 pack the main function, analogy, use cases, filters, and result ordering without excess. Every phrase serves a purpose.

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

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

The description covers purpose, filters, and output ordering. Lacking explicit output fields (no output schema), but the result behavior (newest-first, paginated) is enough for a search tool. Additional info on pagination metadata would improve completeness.

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

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

Schema coverage is 100% with parameter descriptions. The description adds practical context beyond schema, such as how to find fund_id ('discover via whoami or list_funds') and examples for financial_year format, ticker, and transaction_type.

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 searches the transaction ledger across all holdings, with specific use cases ('did we already record this dividend?') and filter options. It distinguishes from sibling list tools by emphasizing search and duplicate-checking.

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 usage scenarios (checking duplicates, looking up past transactions) and implies context (before proposing a new record). It lacks explicit 'when not to use' but is sufficiently clear.

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

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

Annotations indicate the tool is not read-only and not destructive. The description adds context by stating it reverts the state to closed and keeps an audit note. This goes beyond the annotations, though it does not detail all side effects.

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

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

The description is a single sentence covering purpose, context, and constraint. No unnecessary words or repetition.

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

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

For a simple mutation tool with three parameters fully described in the schema, the description covers purpose, constraint, and a side effect (audit note). However, it does not describe the output or success behavior, which is a minor gap given no 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?

All three parameters are described in the input schema with 100% coverage. The description adds no extra meaning beyond what the schema already provides for the 'note' parameter (audit note). 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 reverts a lodged financial year back to closed, with a specific use case (ATO amendment) and a constraint (only works on a lodged year). It distinguishes itself from sibling tools like lodge_financial_year and close_financial_year.

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 a clear condition for use ('Only works on a lodged year') and a typical scenario ('e.g. for an ATO amendment'). However, it does not explicitly mention when not to use or contrast with alternative tools, though the condition implicitly guides the agent.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds context that the transaction returns to 'not yet checked against the statement', which clarifies the exact behavioral change beyond the annotations.

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

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

The description is two sentences, front-loaded with the action and effect, and contains no filler. Every sentence adds value.

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

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

For a simple toggle action with no output schema, the description adequately explains the tool's purpose and relation to a sibling. It could mention prerequisites like the transaction being currently reconciled, but overall it's 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 the baseline is 3. The description does not add any additional meaning to the parameters 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 uses a specific verb 'remove' and resource 'statement-reconciliation tick from a cash row', clearly distinguishing it from its sibling 'reconcile_cash_transaction' by stating it's the inverse.

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

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

The description implies usage when undoing a reconciliation by stating it's the inverse of reconcile_cash_transaction. While it lacks explicit when-not or alternative guidance, the context is clear.

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

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

Annotations indicate write operation (readOnlyHint=false) and potentially destructive (destructiveHint=true). Description adds important behavioral context: it is a 'plain field edit' that does not affect settlement linkage or match status, and is blocked if the financial year is locked. This goes beyond what annotations provide.

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

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

Four sentences, front-loaded with purpose, well-structured with clear exclusions and conditions. Every sentence adds value without redundancy.

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

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

Given 11 parameters, no output schema, and annotations, the description covers essential behavioral aspects, prerequisites, restrictions, and limitations. It is complete enough for an agent to understand how and when to use this tool.

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

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

Schema covers 82% of parameters with descriptions. Description adds value by highlighting the most important parameter (category) with examples and listing other editable fields (description, reference, posted date, amount). However, not all parameters are explicitly mentioned in the description, so schema does most of the work.

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 'Edit an existing cash-ledger row' and lists specific editable fields. Distinguishes from sibling tools by explicitly stating what it does not do (change settlement linkage/match status) and pointing to alternatives (attribute_cash_transaction/detach_cash_transaction).

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

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

Provides explicit when-to-use context (editing category, description, etc.), what it does not do (settlement linkage), and alternatives. Includes prerequisite: find the row via list_cash_transactions. Also mentions blocked condition for locked financial year.

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

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

The description adds value beyond annotations by explaining that the tool upserts by date and, if the newest observation, updates the holding's current price to refresh portfolio values. This is important behavioral context that annotations (destructiveHint: true) do not fully capture. No contradiction with annotations.

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

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

The description is two sentences with a clear structure: action, upsert behavior, side effect, and when to use. It is concise and front-loaded with the verb 'Record,' making it easy for an agent to parse quickly.

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

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

Given no output schema, the description adequately explains the tool's effect (upsert, portfolio refresh) and parameter units. It does not explicitly mention behavior for non-newest observations, but the core functionality is well-covered for a mutation 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 has 100% description coverage, so the baseline is 3. The description reinforces that price is in AUD per unit and implies the date is used for upsert matching, but these are already clear from the schema. No additional semantics beyond the schema are provided.

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 records a price observation for a holding. It specifies the action (record) and resource (price observation), and provides examples of sources. It is distinct from sibling tools like record_cost or record_income, which handle different transactions.

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 advises using the tool 'when you have an updated valuation or a reliable quoted price,' giving clear context for appropriate usage. It does not explicitly state when not to use it, but the context is sufficiently clear for an AI agent to make decisions.

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 discloses key behaviors: rejection of calculated/readonly fields, automatic recomputation of totals, and blank value reverting to ledger-derived figure. Annotations only indicate non-readonly and non-destructive, so the description adds significant 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 concise: three sentences that front-load the purpose, then detail behavioral traits. No unnecessary words or repetition.

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

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

Given the complexity (5 params, no output schema), the description sufficiently explains the tool's behavior, constraints, and return value. Schema covers parameter details well, so the description completes the picture.

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 does not add extra meaning beyond the schema's parameter descriptions, though it reinforces the behavior of the 'value' parameter (blank reverts). No significant additional semantic value.

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

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

The description clearly states it overrides a single field on the return, with specific examples like income and deduction amounts. It distinguishes itself from sibling tools such as get_smsf_return and create_smsf_return by focusing on modifying an existing field.

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 individual field overrides but does not explicitly state when not to use it or suggest alternatives. However, it provides clear context about the safe write path and automatic recomputation.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description details the automatic extraction and reconciliation behavior, including creation of pending proposals. This adds significant value for agent decision-making.

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 cover purpose, process, and post-usage guidance without any wasted words. Essential information is 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 complexity (7 params, no output schema), the description adequately covers behavioral side effects and next steps. However, it omits potential error cases or prerequisite checks, leaving minor 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?

All 7 parameters have schema descriptions (100% coverage), so the description adds only marginal value over the schema (e.g., explaining file reading process). 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 explicitly states the verb 'Upload' and the resource 'local PDF or CSV' with specific document types. It clearly distinguishes from siblings by mentioning downstream tool get_document, and no other upload tool exists among siblings.

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

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

The description advises using get_document after upload to check results, providing a clear post-usage guideline. While it doesn't explicitly contrast with alternatives like reconcile_document, the context is sufficient for most use cases.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds that it returns user info, scopes, and fund IDs, but does not elaborate on rate limits, authentication requirements beyond the API token, or response format. Still, it provides useful behavioral context beyond annotations.

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

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

Single sentence that encapsulates purpose, usage guidance, and key output. Front-loaded and free of 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?

With no parameters and no output schema, the description fully explains the tool's purpose and output (user identity, scopes, fund IDs). It is complete for an identity/discovery tool that should be called first.

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?

No parameters exist, and schema coverage is 100%. The description does not need to add parameter details. According to calibration, 0 parameters gets a baseline of 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?

Clearly states the tool identifies the authenticated user, token scopes, and accessible SMSF funds with fund IDs. This is specific and distinguishes it from siblings, as no other tool provides this identity and fund discovery 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?

Explicitly instructs to call this first in a session to discover fund IDs, and notes that almost every other tool needs a fund_id. Provides clear when-to-use guidance with a rationale.

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