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

The description adds critical behavioral context beyond annotations by requiring user approval before calling. It also notes the required inputs, but does not describe effects on balances or successful/error response behavior. 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?

Three concise sentences front-load the purpose, list requirements, and note the approval constraint. No wasted words or redundant 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?

The description covers required and optional fields plus approval. It could benefit from mentioning how to obtain account IDs (e.g., via list_accounts) and what the tool returns, but given the moderate complexity and lack of output schema, it is reasonably 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 description coverage is 100%, so the baseline is 3. The description recaps required and optional parameters but adds no extra semantic detail beyond what the schema already provides (e.g., date format, amount positivity).

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 specifies the verb 'Add' and resource 'expense transaction to ZenMoney', clearly distinguishing it from sibling tools like add_income and add_transfer by mentioning 'expense'.

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?

It states that account, amount, and date are required and other fields are optional, providing clear usage context. However, it does not explicitly mention when not to use this tool or direct to alternatives like add_income or add_transfer.

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 a non-read-only, non-idempotent, non-destructive operation. The description adds the explicit user-approval requirement, which is a behavioral constraint not captured by annotations, providing useful extra 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 concise sentences, with the core action stated first and the approval requirement second. No redundant wording or unnecessary detail.

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

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

Given the six parameters, high schema coverage, and no output schema, the description covers the essential action but lacks usage context such as prerequisites or relationship to sibling tools. It is adequate but not comprehensive.

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

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

Schema description coverage is 100%, with every parameter documented in its property description. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool adds an income transaction to ZenMoney, using a specific verb and resource. It distinguishes itself from sibling tools like add_expense and add_transfer by naming the transaction type.

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

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

The description does not specify when to use this tool versus alternatives such as add_expense or add_transfer. It only mentions a mandatory user approval step, which is a compliance requirement rather than usage context.

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

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

Annotations already indicate a write operation (readOnlyHint=false), but the description adds valuable behavioral context: the need for user approval, the distinction between cross-currency and same-currency behavior, and the alias relationship between amount and outcome_amount. This goes beyond what annotations provide, though it doesn't describe the response or side effects in detail.

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

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

The description is three sentences long, immediately states the core purpose, and each sentence provides necessary information. There is no redundancy or wasted words, making it highly 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 the tool has 7 parameters and no output schema, the description covers the key complexities (currency handling, approval requirement) but does not mention what the response contains or any prerequisites like account existence. However, the essential usage for an agent is covered, and the missing return details are partially mitigated by the absence of 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?

While the schema covers all parameters (100%), the description adds essential context: it explains the relationship between outcome_amount, income_amount, and the amount alias, and specifies when each is required. This integration of parameters into usage rules significantly enhances understanding beyond the individual schema descriptions.

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

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

The description clearly states the tool's function: 'Transfer money between two accounts in ZenMoney.' This distinguishes it from sibling tools like add_expense and add_income, which handle single-sided transactions. The verb 'transfer' and resource 'two accounts' are specific and immediately clear.

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

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

The description provides clear context on how to handle cross-currency vs same-currency transfers, which indirectly guides the agent on parameter usage. It also explicitly states 'Codex must request user approval before calling this tool,' which is a crucial usage requirement. However, it doesn't explicitly compare with alternative tools or state when not to use this tool, so it lacks explicit exclusions.

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

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

Annotations already indicate a destructive, non-read-only operation. The description adds a critical behavioral requirement: 'Codex must request user approval before calling this tool.' It also specifies 'one existing transaction,' implying the tool does not create transactions. This goes beyond the annotations by mandating an approval step.

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 concise sentences. The first states the core purpose, and the second is a direct approval directive. No wasted words; all content 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?

The tool is simple with only two parameters and no output schema, but the description fails to define what 'category' means or that it should reference an existing category from list_categories. It also omits any details about return values or behavior on invalid inputs. Given the mutation risk and 0% schema coverage, more context is needed for safe and correct invocation.

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

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

Schema description coverage is 0%, and the description provides no explanation of the parameters. The schema only shows types/format (e.g., transaction_id is a UUID, category is a non-empty string) but does not clarify what 'category' should contain—whether it's a category ID, a name, or must come from list_categories. The agent has no guidance on valid values, making correct invocation difficult.

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 action: 'Replace the category of one existing ZenMoney transaction.' It uses a specific verb ('replace') and resource ('category of one existing transaction'), distinguishing it clearly from siblings like delete_transaction or add_expense. The phrase 'one existing transaction' also clarifies it modifies an existing record rather than creating one.

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: this tool is for changing the category of a transaction. However, it provides no explicit when-to-use vs alternatives, such as 'if you need to update other transaction fields, use update_transaction_details instead.' The sibling update_transaction_details likely overlaps, so some exclusion guidance would be beneficial.

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 the approval requirement, which is an important behavioral constraint. However, it does not disclose side effects or response behavior, so it adds limited value beyond annotations.

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

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

The description is two short sentences, both directly relevant: the first states the purpose, the second an approval requirement. There is no filler, 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?

For a create tool with five parameters and no output schema, the description is too minimal. It lacks parameter context, return value information, and usage scenarios, leaving the agent with insufficient information to invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description does not mention any parameter meanings or relationships. The agent receives no guidance on title, kind, parent_category, required_expense, include_in_budget, so the description fails to compensate for the schema's lack of descriptions.

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

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

The description 'Create a ZenMoney category' uses a specific verb and resource, clearly distinguishing it from sibling tools like update_category, delete_category, and list_categories. This provides unambiguous purpose clarity.

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

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

The description includes a procedural note about requesting user approval, but it does not specify when to use create_category versus alternatives such as update_category or merge_categories. No context is given about scenarios that favor this tool.

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

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

Beyond the annotations (destructiveHint=true), the description discloses specific refusal conditions (categories used by transactions or containing children) and an additional requirement (user approval). This adds meaningful behavioral context not present in the annotations, with 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 two sentences, front-loaded with the action, and every phrase adds value (purpose, constraints, approval). No unnecessary fluff.

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

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

For a single-parameter delete with no output schema, the description covers the purpose, constraints, and approval requirement. However, the missing parameter format guidance and lack of any mention of return behavior or error handling leave a minor gap.

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

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

The schema has 0% description coverage for the only parameter 'category', and the description does not clarify whether the parameter expects an ID or a name. This leaves the agent guessing about the correct value format for deletion.

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 deletes an empty ZenMoney category, with the verb 'delete' and resource 'ZenMoney category'. It further distinguishes from siblings like create_category or update_category by specifying the empty condition.

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

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

The description implies the tool should only be used for empty categories by stating it refuses categories used in transactions or containing children. It also adds an explicit usage rule requiring Codex to request user approval. However, it does not explicitly name alternatives for non-empty categories, such as merge_categories.

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 mark the tool as destructive and not read-only. The description adds valuable context beyond annotations by specifying that deletion is permanent (irreversible) and that user approval is required, which are not captured in the structured fields.

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 highly concise with two sentences, front-loading the action and adding the essential safety note. Every word earns its place, with no redundancy.

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

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

For a single-parameter destructive tool with strong annotations, the description provides the necessary behavioral context (permanence, approval) and is sufficiently complete for an agent to invoke it correctly. No output schema is 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?

The schema has one parameter (transaction_id) with 0% description coverage. The description does not explicitly describe the parameter, but the phrase 'one ZenMoney transaction' implies the ID mapping. This is minimal compensation; no additional format or source guidance is given.

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

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

The description clearly states the tool's function with a specific verb ('delete') and resource ('one ZenMoney transaction'). The word 'permanently' distinguishes it from any potential soft-delete or update tools 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 includes an explicit precondition ('must request user approval') which gives some usage context, but it does not mention when to prefer this over alternatives like update_transaction_details or change_transaction_category. No exclusions or alternative pointers are provided.

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

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

No annotations are provided, so the description carries the burden. It discloses a critical precondition (sync required) and the scope of accounts (wallets, cards, cash). However, it does not state whether the operation is read-only, what happens if sync hasn't been done, or the return format, leaving notable gaps.

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 short sentences: the first states the function and scope, the second provides a necessary prerequisite. Every word serves a purpose; no redundancy or filler.

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

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

For a simple list tool with one optional boolean and no output schema, the description covers the essential purpose and prerequisite. It lacks details about error behavior when sync hasn't been performed and does not describe the return structure, but overall it is adequate for a low-complexity 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?

There is one parameter (include_archived) with full schema coverage—its description 'Include archived accounts' is self-explanatory. The tool description adds no extra meaning about this parameter, which meets the baseline but does not elevate it.

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

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

The description uses a specific verb ('List') and resource ('all user accounts'), with clarifying examples (wallets, cards, cash). It clearly distinguishes from sibling tools like list_categories and list_transactions by naming the exact resource type.

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 by stating 'Sync must be done first', establishing a necessary precondition. It does not explicitly name alternatives or when-not-to-use, but the resource focus inherently differentiates it from other list tools.

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

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

With no annotations provided, the description carries the full burden. It discloses the hierarchy structure and the sync prerequisite, which is useful. However, it does not explicitly state read-only behavior or potential outcomes if sync is not performed, leaving some behavioral ambiguity.

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, information-dense sentence. It is front-loaded with the core purpose ('List all expense/income categories') and includes only essential additional context (hierarchy and sync prerequisite). 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 the simplicity of the tool (0 parameters, no output schema), the description adequately covers purpose, scope, and a key prerequisite. It does not describe the return format, but for a straightforward list tool this is a minor omission and the description is otherwise 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?

The tool has 0 parameters, so the empty schema is fully described (100% coverage). The description adds contextual meaning by specifying what the listing includes (expense/income categories and hierarchy), which exceeds the baseline for parameterless tools.

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 all expense/income categories (tags) with hierarchy, distinguishing it from sibling list tools like list_accounts and list_merchants. The verb 'list' and specific resource 'categories' make the purpose unambiguous.

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

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

The description provides clear context by stating 'Sync must be done first,' implying the tool should be used after synchronization. It does not explicitly name alternative tools or when-not-to-use conditions, but the prerequisite offers practical guidance for correct usage.

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

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

With no annotations, the description provides a clear read action and a precondition about sync. It doesn't describe any side effects or output details, but for a list tool the action is transparent enough. It could be more explicit about being read-only.

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

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

Two sentences, no wasted words, action is front-loaded. The dependency on sync is stated efficiently.

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

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

For a zero-parameter list tool with no annotations, the description covers the purpose and the important sync dependency, making it 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?

The input schema has zero parameters, so the baseline is 4. No parameter details are needed, and the description doesn't add anything about parameters.

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 'List known merchants/payees' with a specific verb and resource. It distinguishes itself from sibling list tools by naming merchants/payees explicitly.

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?

It specifies a clear precondition: 'Sync must be done first,' implying this tool should be used only after sync_data. However, it doesn't explicitly name alternatives or exclusions.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It discloses the default date range and the sync prerequisite, which are useful traits, but it does not describe return format, ordering, pagination, or behavior when sync hasn't been performed.

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 verb, and every sentence adds value. No redundant or filler content.

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 6 parameters, no annotations, and no output schema, the description covers the most critical context: the sync prerequisite and default time window. However, it omits mention of filters and response format, which the agent must infer from the schema and tool name. This is adequate but not exhaustive.

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% parameter coverage, so the baseline is 3. The description adds a concrete date-range example (Jan 1–31) and clarifies the default window, providing some additional meaning beyond the schema's descriptions. It does not detail filters or limit, but the schema already covers those.

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 'List transactions', a specific verb+resource, and adds a scope qualifier (default last 30 days) that distinguishes it from sibling list tools like list_accounts and list_categories. The name itself is unambiguous.

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

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

It explicitly states a prerequisite ('Sync must be done first'), giving the agent clear when-to-use context. It also explains how to request a custom date range via start_date/end_date. However, it does not name alternative tools or state 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?

The annotations already declare destructiveHint=true, so the destructive nature is known. The description adds valuable context beyond the annotations: it specifies that the source must be a leaf category, that transactions are moved before deletion, and that Codex must request user approval. This goes beyond the basic destructive flag and provides useful behavioral detail.

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

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

The entire description consists of two brief, information-dense sentences with no filler. It is front-loaded with the main action and includes the critical approval requirement in a concise manner.

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 two-parameter destructive tool, the description is largely complete. It specifies the operation order, the leaf-category constraint, and the approval requirement. It lacks details about return values or error handling, but given the absence of an output schema and the tool's simplicity, the provided information is sufficient for an agent to invoke it correctly.

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

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

With 0% schema description coverage, the description must compensate. It explains the roles of the parameters as 'from' (source_category) and 'into' (target_category), and indicates that source is deleted. However, it does not elaborate on whether parameters are IDs or names, or confirm that target must also be a leaf category. It provides only minimal semantic addition over the parameter names.

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

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

The description clearly specifies the action: 'Move transactions from one leaf category into another, then delete the source.' It uses a specific verb and resource, and distinguishes itself from sibling tools like update_category or change_transaction_category by describing the combination of moving transactions and deleting the source category.

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 conveys the core action but does not explicitly state when to use this tool versus alternatives such as change_transaction_category for individual moves or delete_category for simple deletion. The approval requirement is mentioned, but no explicit 'when to use' or 'when not to use' 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?

It explicitly states 'never changes data' and 'Returns transaction IDs,' which are key behavioral traits. Given no annotations, this disclosure is valuable. However, it doesn't mention parameters' effects or potential costs.

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 clear sentence with no filler words, front-loading the main 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?

For a tool with no output schema and no annotations, the description covers the primary behavior and safety, but lacks parameter details and usage context, making it incomplete for a complex tool.

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

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

The schema has no descriptions for its 4 parameters, and the description does not directly explain them. It indirectly maps 'period' to start/end dates and 'unusually large' to large_amount_rub, but duplicate_window_days remains unexplained. This partial compensation is not enough.

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 (review) and clear resource (a period for duplicate, uncategorized, and unusually large transactions). It distinguishes itself from sibling mutation tools by explicitly stating it returns transaction IDs and never changes data.

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

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

The description implies its purpose (analyzing transactions) but does not explicitly state when to prefer it over list_transactions or suggest_category. It lacks exclusionary guidance like 'use this for review only, not for editing.'

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

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

No annotations are provided, so the description must convey behavioral expectations. It states it is a 'Get' operation ('auto-suggestion'), which implies a read-only, non-destructive action. However, it does not disclose the response format (e.g., whether it returns a single suggestion or multiple, confidence scores, or behavior for unknown payees). The description is adequate but leaves gaps in behavioral transparency.

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

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

The description is exceptionally concise, consisting of two short sentences (18 words). It is front-loaded with the core action ('Get ZenMoney's auto-suggestion') followed by the input and use case. Every word adds value, and there is no redundancy or filler.

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

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

The tool is simple: one string parameter, no output schema. The description adequately explains what it does, why it is useful, and identifies the key input. It does not mention error behavior or return format, but given the simplicity, it is mostly complete. The absence of annotations and output schema means the description could offer slightly more, but it still provides sufficient context for a simple read-only suggestion utility.

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% since the only parameter 'payee' is described as 'The payee/merchant name from the receipt.' The tool description adds minimal extra meaning by mentioning 'payee name' and 'receipts,' but this largely repeats the schema. No additional parameter details are provided beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get ZenMoney's auto-suggestion for category and merchant based on a payee name.' The verb 'Get' and the specific resource ('auto-suggestion for category and merchant') make the purpose unambiguous. It also distinguishes from sibling tools like list_categories and create_category by focusing on the suggestion feature rather than direct category management.

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 phrase 'Useful for categorizing receipts' provides a clear context for when to use this tool. However, it does not explicitly mention alternatives or cases where this tool should not be used, despite having many sibling tools for category and transaction management. The use case alone gives sufficient guidance for an agent to decide when to invoke 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals that sync is incremental by default with an optional full re-download, and that it is a prerequisite step. However, it does not disclose whether the sync is one-way or two-way, what happens to local changes, or any authentication/rate-limit considerations.

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 just two sentences, front-loaded with 'Sync data with ZenMoney.' Each sentence earns its place: the action, the prerequisite ordering, and the parameter usage. There is no wasted or redundant text.

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

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

For a tool with a single optional boolean parameter and no output schema, the description covers the essential points: what it does, when to run it, and how to force a full sync. It lacks detail on directionality or failure behavior, but given the tool's simplicity, it is reasonably 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 description coverage is 100%, so the baseline is 3. The description's phrase 're-download everything' adds a practical effect to the force_full parameter, but it largely restates the schema's 'Force a full sync instead of incremental' without adding significant new semantic depth.

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

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

The description uses the verb 'Sync' with a clear resource 'data with ZenMoney', and the instruction 'Run this first before using other tools' distinguishes it from all sibling CRUD/list tools. It clearly identifies this as a synchronization operation that prepares data for the other tools.

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

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

The phrase 'Run this first before using other tools' provides explicit sequencing guidance, while 'Use force_full=true to re-download everything' gives a specific use case for the parameter. It does not explicitly state when not to use it, but the sibling tools handle post-sync operations, making the intended context clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds a mandatory user approval step, which is operational context beyond the annotations. It does not contradict annotations and offers a useful safety guideline.

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 concise sentences with no filler. The first sentence delivers the core purpose, and the second adds a critical operational instruction, making it well-structured and 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 seven parameters and no output schema, the description is too sparse. It lacks details on return values, parameter interactions, validation rules, and the consequences of configuration changes. The approval note is helpful but does not compensate for the missing guidance.

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

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

Schema description coverage is 0%, and the description only says 'rename or configure' without explaining the seven parameters. The agent must rely on parameter names (e.g., new_title, kind, clear_parent) to infer meaning, which is insufficient for a parameter-heavy mutation tool.

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 that the tool renames or configures an existing ZenMoney category, which distinguishes it from create_category, delete_category, and merge_categories. The verb 'rename or configure' plus 'existing' makes the purpose specific and unambiguous.

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

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

The description implies usage for modifying an existing category but does not explicitly contrast with alternatives like create_category or delete_category. The approval requirement is a usage note but not about when to choose this tool over others.

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

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

The description adds valuable behavioral context beyond the annotations: 'Omitted fields stay unchanged; null clears a field' explains partial update semantics, and 'Codex must request user approval' is a critical operational constraint. This goes beyond the destructiveHint and readOnlyHint flags.

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

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

The description is two sentences long, with the first stating the core purpose and the second adding essential behavioral rules. 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 update tool with three parameters and no output schema, the description fully covers what is updated, how omitted/null values behave, and the approval requirement. It is complete enough for an agent to invoke correctly without further clarification.

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 67%, and the description compensates by explaining that omitted fields are left unchanged while null clears them—this is not explicit in the schema. It also clarifies the 'payee/payer' field meaning. The transaction_id semantics are left to the schema, which is acceptable.

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 ('Update') and resource ('one existing ZenMoney transaction'), and explicitly names the fields affected ('payee/payer and/or comment'). This clearly distinguishes it from sibling tools like change_transaction_category or delete_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 on what the tool does (updates payee/comment of one transaction), making it easy to infer when to use it. However, it does not explicitly mention alternatives or exclusions, though the sibling tool list helps. The approval requirement is also stated.

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