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

Corroborates and enriches the annotations (idempotentHint=false, destructiveHint=true) with a worked arithmetic example (100 onto 250 leaves 350) and a clear statement that repeated calls compound. It does not discuss permissions, reversibility of a mistaken assignment, or currency/precision handling, so it stops short of full disclosure.

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 action and direction are front-loaded in sentence one, and the retry warning is well placed. The closing sentence about NEED targets is the weakest link – it is vague ('usually assigned every month, whatever is available') and adds bulk without a crisp rule.

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 annotations carrying the safety profile and an output schema present, the description covers the mutation's additive nature and its retry hazard, which is what an agent needs before calling it. It omits any mention of how it relates to set_assigned/move_money or what error conditions look like beyond the retry warning.

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 earns an extra point by clarifying delta semantics with a concrete stacked-assignment example and by pairing negative amounts with the Ready to Assign return path. The month parameter is left entirely to 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 first sentence names a specific verb (assign) and resource (money to a category from Ready to Assign) and states both directions of the operation. 'This adds to what is already assigned' implicitly separates it from the set-based sibling set_assigned without needing the schema.

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 concrete operational guidance: negative amounts reverse the flow, and it explicitly warns against blind retries after an error, pointing to get_month_category as the verification step. It does not explicitly compare against set_assigned or move_money, so the agent must infer the choice from the additive wording.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the write/safety profile is covered. The description adds the meaningful behavioral point that the created account has no bank link, but says nothing about duplicate-name handling, whether the account can later be linked, or what a non-idempotent repeat call does.

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, no filler, and the key scope constraint ('tracked by hand') appears before the clarifying 'not connected to a bank.' 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 three-param creation tool with full schema coverage and an output schema, the description covers what is created and the manual-account scope. It is slightly thin on post-creation behavior (duplicates, visibility in list_accounts), but nothing essential to making the call is missing.

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 all three required parameters documented including the enum values for 'type' and the negative-balance convention for 'balance'. The description adds no parameter-level meaning beyond the schema, so the baseline 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 gives a specific verb and resource ('Create an account') and immediately scopes it to manually tracked accounts like cash or savings, with the clarifying constraint 'not connected to a bank.' It does not reference any sibling tool (e.g. list_accounts) to sharpen the boundary, so it stops short of full 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?

'Create an account that the user tracks by hand' plus 'not connected to a bank' effectively states the condition under which this tool applies and implicitly excludes synced bank accounts. No alternative tool or follow-up action (e.g. how to record transactions afterward) is named, so it is clear context rather than explicit 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 it is a non-read-only, non-idempotent, non-destructive, closed-world write, so the safety profile is covered. The description adds nothing beyond that: no mention of uniqueness constraints on name, what happens if the group id is invalid, or the default behavior when target_amount is supplied without frequency (the schema notes a monthly NEED target is created).

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

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

A single short sentence with no redundancy, but it is terse to the point of under-specification — the 'optionally with a target' clause is the only non-obvious content and it is left unexplored.

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?

An output schema exists and the input schema is fully described, so most information is available elsewhere. However, for a 7-parameter creation tool with no annotations covering validation or defaults, the description should do more than one sentence to be considered 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 all seven parameters are already documented in the schema, including the target_* interaction rules. The description only gestures at the optional target without adding format or interaction detail beyond the schema; baseline 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?

States a specific verb and resource ('Create a category') plus its containment ('in a category group') and the optional target aspect. It is distinguishable from list_categories, update_category, and create_category_group at a glance, though it doesn't explicitly name those 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?

No guidance on when to use this versus update_category (e.g. category must not already exist) or create_category_group. Nothing about prerequisites such as needing a valid existing category_group_id, and no exclusions are stated.

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 this is a non-read-only, non-destructive, non-idempotent, closed-world mutation, so the safety profile is covered. The description adds only the 'empty' detail — nothing about name uniqueness, error behavior on duplicates, or limits beyond the schema's 50-character cap.

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?

One short sentence with the verb front-loaded and no filler. There is no wasted text and nothing is buried.

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?

An output schema exists, so return values need no explanation, and annotations cover the mutation profile. However, for a create operation the description leaves open practical questions (uniqueness of name, where the group surfaces) that a slightly longer description could close.

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% and the single 'name' parameter is documented with a 50-character limit, so the schema carries the semantics. The description contributes nothing about the name beyond what is already structured; baseline 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?

States a specific verb and resource ('Create ... category group'), and the qualifier 'empty' signals that no categories are included at creation. It does not contrast with siblings like create_category or rename_category_group, but the action 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?

There is no guidance on when to use this versus create_category (which presumably also needs a group) or how it fits with list_category_groups. The agent must infer that a group must exist before categories can be assigned to 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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description adds the useful workflow fact that transactions can self-create payees, but says nothing about duplicate handling, whether a name collision errors or succeeds, or what the output contains – relevant gaps for a non-idempotent write.

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, front-loaded with the action and followed immediately by the disambiguation. Nothing is repeated from the schema or annotations.

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?

A one-parameter create tool with an output schema and full annotation coverage needs little more: the agent knows what it does, when it is unnecessary, and that the result is returned in a defined shape. Nothing required for correct invocation is missing.

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% and the only parameter (name) is documented with its 500-character limit and required status. The description adds no parameter-level meaning beyond the schema, so the baseline 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?

States the specific verb and resource ('Create a payee') and contrasts it with the implicit alternative of letting a transaction auto-create the payee via payee_name, so an agent can tell it apart from the transaction-creation path without reading the schema. It stops short of naming the concrete sibling tool by name, keeping it at a 4.

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 explicit when-to-use guidance ('only needed to set up a payee before any transaction uses it') and implicitly says when not to use it. It does not address what happens if the payee already exists, which matters given idempotentHint=false.

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 this is a non-read-only, non-idempotent, non-destructive, closed-world mutation, so the safety profile is covered. The description adds nothing beyond that: it does not say whether scheduling creates future transactions automatically, whether duplicates are created on repeat calls (relevant given idempotentHint=false), or what the required permissions are.

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

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

A single well-formed sentence with no filler and the core purpose front-loaded. It is efficient, though its brevity borders on under-specification rather than tightness.

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?

An output schema exists and parameters are fully documented, so the description needn't cover return values. However, for a ten-parameter mutation that establishes a recurring schedule, the description omits the one thing structure cannot convey: how scheduled transactions behave (auto-creation of future entries, effect of the date/frequency pairing).

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% and all ten properties carry meaningful descriptions, including the frequency enum and the payee_id vs payee_name interaction. The description adds no parameter-level meaning beyond the schema, 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 gives a specific verb (schedule) and resource (transaction) and adds examples of what that means in practice: bill, paycheck, regular transfer. It does not, however, distinguish this from sibling create_transactions (one-time) or update_scheduled_transaction, so sibling differentiation is left to the name alone.

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

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

There is no explicit guidance on when to use this versus create_transactions for a single-dated transaction, nor when to use it versus update_scheduled_transaction or enter_scheduled_transaction. The agent must infer the scheduling lifecycle entirely from tool names.

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 this is a non-idempotent, non-destructive write. The description reinforces the non-idempotent behavior with 'Calling this twice enters the transactions twice,' which is exactly the kind of context an agent needs. It does not discuss permissions or partial-failure behavior, but with annotations covering the safety profile this is strong.

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 purpose is front-loaded, followed by usage, a duplicate warning, and compact examples. Every sentence carries information an agent needs to construct a correct call.

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 complex batch-mutation tool with nested splits and transfers, the description covers the main entry patterns and the duplication hazard. It omits preconditions like account existence and error/partial-failure behavior, but an output schema exists and the input schema is fully annotated, so only minor gaps remain.

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, but the description adds meaningful example patterns: transfers use transfer_account_id with no category, income uses 'Inflow: Ready to Assign', and splits show component amounts. These examples clarify semantics beyond field-level documentation.

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

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

The first sentence gives a specific verb (Create), resource (transactions), and scope (one or more in one request). It does not explicitly contrast with siblings like update_transactions or import_transactions, but the batch-create intent is unmistakable.

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 lists concrete use cases (receipt spending, income, transfers, splits), which tells an agent when to reach for this tool. It also warns that calling twice duplicates entries, a crucial usage constraint. However, it does not name alternatives or state 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description still adds genuinely new context: deletion is non-cascading ("Transactions it already entered stay") and requires user confirmation, which no structured field conveys. It stops short of saying the schedule deletion itself is irreversible or what happens to a bad ID.

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 short sentences, front-loaded with the action and its effect, then the scope caveat, then the confirmation requirement. No filler and nothing an agent must read past to find the core operation.

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 an output schema present and full schema description coverage, the description only needs to cover behavior, which it largely does: effect, non-cascading scope, and confirmation. The missing piece is whether the schedule deletion can be undone, a meaningful gap for a destructive tool.

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

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

Schema description coverage is 100% on a single required parameter, so the schema already explains scheduled_transaction_id as the UUID of the schedule to delete. The description adds no format, lookup, or validation guidance beyond that, making the baseline 3 correct.

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?

States a specific verb and resource ("Delete a scheduled transaction") plus the practical effect ("so it stops happening"), which separates it from delete_transaction and update_scheduled_transaction by resource name. It does not explicitly name the sibling to use instead when the intent is to skip only one occurrence.

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 gives one concrete operational guideline — "Confirm with the user before deleting" — which is real usage guidance. However, it never addresses the main ambiguity for an agent: when to delete the schedule versus using update_scheduled_transaction to change it or enter_scheduled_transaction to record an occurrence.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered by structured data. The description adds the confirmation requirement, a real behavioral instruction beyond the annotations, but does not say whether deletion is permanent or what side effects occur (e.g., impact on account balance).

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 with zero filler, and the confirm-before-deleting warning is front-loaded where an agent will see it. Nothing is padded or redundant.

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?

An output schema exists and annotations cover the safety profile, and the single parameter is fully documented, so the basics are complete. Still missing is whether deletion is irreversible or has cascading effects on related records, which matters for a finance-domain 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?

Schema description coverage is 100% for the single transaction_id parameter, so the schema already fully documents it. The description adds no format, sourcing, or validation detail beyond that, making the baseline 3 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?

States a specific verb (delete) and resource (a transaction), which is unambiguous on its own. It does not explicitly distinguish itself from update_transactions or delete_scheduled_transaction, relying on the name for 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?

The instruction 'Confirm with the user before deleting' gives a clear operational precondition, which is genuinely useful. However, there is no guidance on when to delete versus update/correct a transaction, nor any mention of alternatives among the many 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?

Adds substantial context beyond the annotations: the schedule advances to the occurrence after next, one-time schedules are deleted, and repeat calls create duplicate transactions (consistent with idempotentHint=false and destructiveHint=true). What it doesn't cover is the failure mode for unsupported schedule types — whether the call errors out or silently does nothing.

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?

Front-loaded with the action and its trigger, then the state changes, then the limitations, then the duplicate-call warning — a natural decision order. No sentence is redundant; the YNAB analogy and the 'twiceAMonth' exclusion each carry distinct 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 destructive, non-idempotent mutation with an output schema, the description covers everything an agent needs to decide and act: when to use it, what it mutates, what it deletes, and which inputs it rejects. Return-value details are correctly left to the 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 100%, so all four parameters (including date defaulting to today and memo/amount defaults) are already documented. The description only indirectly touches the date parameter via 'before its date' and says nothing about memo or amount overrides, so it does not add meaning beyond the schema. Baseline 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?

States a specific verb+resource (enter a scheduled transaction early) and pins down the semantics with the YNAB 'Enter Now' analogy and 'before its date'. This clearly separates it from create_scheduled_transaction and update_scheduled_transaction, which act on the schedule itself rather than materializing an occurrence.

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 an explicit trigger ('when a bill is paid early or a paycheck arrives early') and explicit exclusions (split schedules and 'twiceAMonth' cannot be entered this way — use YNAB). It even warns that a second call enters a second occurrence, which preempts the most likely misuse.

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 openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail by specifying case-insensitive substring matching. It omits result ordering or no-match behavior, but the output schema covers return structure.

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 core behavior is front-loaded in a single sentence, followed by illustrative examples. The three examples are somewhat repetitive but each demonstrates a different phrasing of the same underlying query, so they earn their 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 annotations, a complete input schema, and an output schema, the description provides enough context to call the tool correctly. The only minor gap is absence of guidance on result ordering or behavior when there are zero matches.

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 both name_search and limit are fully documented in the input schema. The description's examples reinforce name_search usage but add no syntax or constraint information beyond what the schema already provides. 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?

States a specific verb ('Find'), resource ('payees'), and matching scope ('names contain a search term, ignoring case'). This clearly distinguishes it from sibling list_payees (which has no filter) and write tools like create_payee or rename_payee.

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 example queries map natural-language intents to name_search values, which gives clear usage context. However, it does not explicitly state when to use this versus list_payees or what happens when no match is found, so the guidance is strong but not exhaustive.

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 openWorldHint=false, so the safety profile is covered. The description adds which budget figures are returned (assigned, activity, available, target), which is mildly useful, but says nothing about permissions, missing-category behavior, or how the values are scoped.

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

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

A single front-loaded sentence with zero filler; the key scope words ('one category', 'for a month') come first.

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 annotations, full schema coverage, and an output schema, the description only needs to frame the call, which it does. The one residual gap is that it doesn't relate the tool to its closely-named siblings, leaving routing slightly under-specified.

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

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

Schema description coverage is 100%, including a detailed enum/date explanation for 'month' and a required note for 'category_id', so the schema carries the parameter burden. The description only restates the category and month framing, adding no syntax or format detail 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 names a specific verb ('Get') and resource ('one category's assigned, activity, available, and target for a month'), and the phrase 'one category' implicitly distinguishes it from month-wide siblings like get_plan_month. It never names a sibling explicitly, so an agent must infer the boundary from the phrasing.

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?

Usage is implied by 'for a month' on a single category, but there is no explicit when-to-use, when-not, or pointer to alternatives such as get_plan_month or list_categories. The agent has to reason about the boundary itself.

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 openWorldHint=false, so the safety profile is covered. The description adds real value on top: the exact fields returned and the practical rule that the returned currency format should drive how amounts are displayed to the user. It does not discuss caching or whether plan settings can shift mid-session, but with annotations carrying the safety burden this is solid.

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, front-loaded with the returned fields, then the one actionable tip. Nothing is repeated or padded.

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?

Zero params, no nested objects, an output schema, and read-only annotations mean the description only needed to frame purpose and any non-obvious usage. It does that, plus the currency-format tip. Minor gap: it never clarifies which plan is returned (last-used vs. default), which an agent might wonder about.

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 takes zero parameters, so the baseline is 4. The description correctly implies a no-argument call that returns the current plan's metadata, consistent with the empty 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?

States a specific verb and resource ('Get the plan') and enumerates exactly what comes back: name, months covered, currency and date formats. That field list implicitly separates it from get_plan_month and list_plan_months, which drill into per-month data, though no sibling is named outright.

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 only guidance is output-side: 'Use the currency format to write amounts the way the user sees them in YNAB.' There is no statement of when to call this versus get_plan_month or list_plan_months, and no prerequisites; usage is inferred from the zero-arg, plan-level nature of the 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful scope context by naming the returned fields and flagging that only *visible* categories appear, which hints at permission-based filtering. It does not mention pagination despite limit/offset parameters, which is a real behavioral gap for a tool returning a category list.

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

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

A single front-loaded sentence with a specific verb and a compact field list; every clause conveys returnable data rather than filler. No redundancy with the title beyond the unavoidable tool name.

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 an output schema present and all three parameters fully documented, the description only needs to convey scope, which it does well by listing the month's components. The one omission is that paginated category results exist but go unmentioned in the description.

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% and the month parameter is already fully documented with enum meanings and date format, so the schema does the heavy lifting. The description adds nothing about which parameter controls the category pagination or how "current" resolves. 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?

States a specific verb and resource ("Get one month of the plan") and enumerates the exact payload: income, assigned, activity, Ready to Assign, age of money, and per-category amounts. The scoping to a single month implicitly separates it from get_plan and list_plan_months, though no sibling is named outright.

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

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

No statement of when to call this versus get_plan (whole-plan view), list_plan_months (month inventory), or get_month_category (single category detail), all of which appear in the sibling list. The use case is inferable from the description but never stated, and no prerequisites or exclusions are given.

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 openWorldHint=false, so the safety profile is covered, but the description adds nothing beyond that — no note on not-found behavior, no indication the record is a template rather than a posted transaction. For a read with rich annotations the bar is lower, yet zero added context is still weak.

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?

One short, front-loaded sentence with no filler, so it is concise. However, the brevity reflects under-specification rather than tightness — nothing beyond the bare minimum is stated.

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 required ID, full schema coverage, and an output schema so return values need not be described. Given that, the description is minimally sufficient, though it omits any guidance on where the ID comes from or how it differs from get_transaction.

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 a single parameter at 100% schema description coverage (uuid format, required, described as the transaction to get), the schema carries parameter meaning fully. The description adds no syntax or sourcing detail, so baseline 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?

"Get one scheduled transaction" essentially restates the tool name and title without adding scope or disambiguation. It does identify verb and resource, but an agent gets no help distinguishing it from get_transaction or list_scheduled_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?

There is no when-to-use guidance, no mention of the sibling list_scheduled_transactions for fetching many, and no note on whether the ID must come from that listing first. The agent must infer all routing from the name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one substantive behavioral detail — that split parts are included — but says nothing about missing-ID behavior or the scope of the returned record.

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

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

A single front-loaded sentence with no filler, and the differentiating detail (split parts) arrives immediately. Nothing is wasted.

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 an output schema covering the return shape and annotations covering the read-only safety profile, the description only needs to establish scope and the split nuance, which it does. The slight gap is the absence of any error/not-found or sibling-routing context.

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 a single required parameter, so the schema already defines transaction_id fully. The description adds no format, source, or lookup guidance beyond what the schema provides, making baseline 3 correct.

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?

States a specific verb and resource ('Get one transaction') and the singular scope distinguishes it from the sibling list_transactions. It stops short of explicitly naming that sibling, so the differentiation is implied rather than stated.

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 'one transaction' implies lookup by ID, which implies use when you already have a transaction_id, but the description never says when to prefer this over list_transactions or what happens if the ID is unknown. Usage is inferable but not guided.

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-read-only, non-idempotent, non-destructive, closed-world. The description adds genuinely non-derivable behavior: the import is a request to YNAB and results land as unapproved transactions, plus how to retrieve them. It does not state whether the call returns immediately or blocks, which is the one remaining behavioral unknown.

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 short sentences: what it does, the timing it replaces, and the follow-up. Front-loaded with the action, no repetition of the title, zero waste.

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-param trigger with annotations covering the safety profile and an output schema covering the response shape, everything an agent needs is present: the action, its timing semantics, and how to observe the result afterward. Nothing material is missing.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly spends no words on inputs and instead explains downstream effects.

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?

States a specific verb+resource: trigger a bank-account transaction import from the plan's linked accounts, explicitly contrasted with the next scheduled import. It implicitly separates itself from create_transactions (manual entry) via 'linked bank accounts', but never names that sibling, so differentiation is inferred rather than stated.

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 a clear triggering condition ('now, instead of waiting for its next scheduled import') and a concrete follow-up path (list_transactions with status="unapproved"). No explicit when-not or exclusions, but the use case is unambiguous for a zero-param action.

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 establish read-only and closed-world behavior, and the description adds useful context that accounts include balances and transfer_payee_id. It does not discuss pagination or whether closed accounts are included by default, but those details are covered by the schema.

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

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

Two short sentences with no wasted wording. The core action and resource are front-loaded, followed immediately by the most useful field-level context.

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

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

For a simple read-only listing tool with fully described parameters, annotations, and an output schema, the description provides enough context to select and invoke it correctly. The transfer_payee_id note adds practical orientation without needing to repeat schema or output details.

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 limit, offset, and include_closed are already fully documented in the schema. The description adds no additional parameter semantics beyond what the schema provides, making 3 the appropriate 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?

Clearly states the specific action (list) and resource (the plan's accounts), and adds that balances are included. It does not explicitly differentiate from sibling tools such as create_account or list_payees, so it falls short of 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?

The description explains a practical follow-up use for transfer_payee_id when transferring money into an account, but it does not state when to choose list_accounts over related siblings or when not to use it. Usage is implied rather than explicitly guided.

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 useful behavior beyond the read-only annotations: only visible categories are returned, hidden and deleted categories are excluded, and results follow the plan's group-by-group ordering. It does not cover pagination behavior, but the schema already documents limit and offset.

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 short, front-loaded with the core purpose, and every sentence contributes useful information about scope, filtering, or ordering. There is no wasted text.

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

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

The description is largely complete for a simple list tool: it explains what is returned, which categories are excluded, and how results are ordered. With annotations, full parameter schema coverage, and an output schema, the remaining omissions are minor.

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 both limit and offset are already well documented in the input schema. The description does not add parameter-specific meaning beyond what the schema provides, which is acceptable at 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 states a specific verb and resource: list the plan's categories, including this month's amounts and targets. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings such as list_category_groups or get_month_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?

Usage is implied by the description: use this to list categories in plan display order. However, there is no explicit guidance on when to use this versus list_category_groups, get_month_category, or other category-related 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral fact — the results carry this month's aggregated totals rather than raw categories — but says nothing about ordering, empty groups, or plan-month edge cases. Modest value 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?

Two short sentences, each earning its place: the first defines output content and scope, the second handles routing. The differentiating detail is front-loaded rather than buried.

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, an output schema to explain return values, and read-only annotations, the description covers everything needed to invoke the tool correctly. The only minor gap is not clarifying whether 'this month' means the calendar month or the selected plan month.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly does not invent parameter discussion.

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?

States a specific verb and resource ('List the plan's category groups') plus the scope of the data returned ('this month's totals'). The second sentence explicitly distinguishes it from the sibling list_categories, so an agent can pick between them without opening a schema.

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?

Names the concrete alternative (list_categories) and the exact condition that selects this one ('when only the overview by group is needed'), including the tradeoff ('lighter'). Both when-to-use and which-sibling-not are explicit.

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 openWorldHint=false, so safety and scope are covered. The description adds that each entry conveys amount, source, destination, and time, but says nothing about pagination behavior, ordering, or result size beyond what the params declare. With annotations carrying the safety profile, this is 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 short sentences with zero waste; the resource definition comes first and the motivating use case second. Nothing is repeated from the schema or annotations.

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?

An output schema exists and the input schema is fully documented, so return values and parameter details need not be in the description. Purpose and usage are both covered; only minor context such as ordering or how pagination interacts with the month filter is absent.

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%, and the limit/offset/month parameters are fully documented in the schema including enum meanings and defaults. The description adds no parameter-level meaning beyond that, 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?

States a specific verb ('List') and a specific resource ('history of money assigned and moved between categories'), which cleanly separates it from ledger-oriented siblings like list_transactions and from mutating siblings like assign_money and move_money. The second sentence reinforces what the resource represents rather than restating the name.

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 an explicit use case: explaining why a category's assigned amount changed. That tells the agent when to reach for it, but it does not name alternatives or exclusions (e.g., use list_transactions for actual bank activity, or assign_money/move_money to change amounts).

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 openWorldHint=false, so safety and scope are covered. The description adds genuinely new behavior: results are sorted by name and soft-deleted payees are omitted, which an agent needs to interpret an empty or short result set. It leaves paging behavior implicit, but the schema carries that.

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 short sentences with zero waste: purpose first, then the domain gloss, then the routing advice and the exclusion note. Every sentence carries information the agent could not get from structured fields.

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 a 2-parameter schema at full coverage, read-only annotations, and an output schema, the only gaps left are return format and pagination mechanics, both already structured. The description covers the remaining semantic questions (ordering, deleted records, when to use a sibling instead).

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%, and both limit and offset are fully documented there with defaults, so the schema does the heavy lifting. The description adds nothing about pagination strategy or page-size tradeoffs, so baseline 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?

States a specific verb and resource ('List the plan's payees') plus the ordering ('sorted by name'), which an agent cannot infer from the name alone. It also defines what a payee is, removing ambiguity about the resource, and explicitly distinguishes itself from find_payee.

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?

Names the alternative tool (find_payee) and the exact condition that selects it ('to find a particular payee'), calling it 'much faster than paging through this list'. It also states the enumeration rule that deleted payees are excluded, so the agent knows what this list will and won't contain.

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 openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing result ordering (newest first) and the specific content of the returned totals, which the agent cannot get from the annotations alone.

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 with the core operation and ordering front-loaded, followed by one sentence of usage context. No filler 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?

An output schema exists, parameters are fully documented, ordering is stated, and the description names the metrics returned. What remains unstated is how pagination interacts with the 'newest first' ordering, 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?

Schema description coverage is 100% and both limit and offset are documented inline, including defaults. The description adds no pagination or parameter semantics beyond the schema, so baseline 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?

States a specific verb and resource ('List the plan's months with their totals') plus the ordering ('newest first'), so the operation is unambiguous. It does not explicitly name the singular sibling get_plan_month, so differentiation from that tool is left to be inferred from the name.

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?

'Use this for trends over time' gives a clear positive selection context and enumerates the specific trend dimensions (income, assigned, activity, Ready to Assign, age of money). It stops short of naming an alternative such as get_plan_month for a single month, so there is no exclusion 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the meaningful traits that filters are combinable (AND semantics) and that results are ordered soonest-first, but says nothing about pagination totals or result volume beyond what limit/offset already imply.

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 core statement is front-loaded in a single sentence, followed by a compact example block. Each example carries a concrete parameter mapping rather than filler, though four examples is slightly more than strictly needed for nine self-documented parameters.

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 an output schema present, annotations covering safety, and 100% schema coverage on all nine params, the description only needs to add the non-obvious traits — it does that via filter combinability and render order. Minor gaps remain around result volume/pagination behavior and cross-tool sequencing beyond the payee hint.

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 limit, offset, payee_id, frequency, amounts, account, category and upcoming_days are all already documented in the schema. The description's examples largely restate those semantics; the one genuine addition is the workflow hint that payee_id requires resolving the payee first (presumably via find_payee). That justifies the baseline 3 but not more.

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?

States a specific verb and resource ('List scheduled transactions') plus a meaningful implicit sort ('soonest first'), which separates it from the plural list_transactions and the singular get_scheduled_transaction. It does not explicitly name a sibling or state exclusion conditions, so it stops short of 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?

The example-query block effectively maps natural-language intents to concrete parameter choices (frequency="monthly", upcoming_days=7, min_amount=100), giving clear context for when each filter applies. It omits when not to use this tool or which sibling to prefer for single-record or posted-transaction lookups.

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 openWorldHint=false, so safety is covered; the description adds genuinely non-obvious behavior — newest-first ordering and that category/payee filters explode splits into separate rows with parent_transaction_id set. It doesn't discuss pagination limits or result size, but the key behavioral risk (split rows inflating counts) is disclosed.

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?

Purpose is front-loaded in one sentence, followed by scannable example mappings and a final caveat sentence. Each block earns its place; the examples are dense with mapping information rather than 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?

With 11 optional params, an output schema present, and rich annotations, the description covers the remaining burden well: ordering, combinability, split-row behavior, and intent-to-parameter mapping. Only pagination/result-size expectations are left implicit.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds value beyond the schema by showing parameter combinations in context (e.g., payee_id + date range for 'Amazon in March') and interpreting status values through intent questions. This is real semantic value the property docs alone don't convey.

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?

States a specific verb and resource plus ordering ('List transactions, newest first') and that filters combine. It doesn't explicitly distinguish itself from get_transaction, but the list-vs-single distinction is clear from the name pairing.

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?

Worked example queries map natural-language intents to concrete parameter sets, which tells an agent when this tool fits and how to configure it. It stops short of naming alternatives (e.g., get_transaction for a known ID) or stating exclusions, so it isn't full 5-level routing 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?

Despite annotations already marking this as destructive and non-idempotent, the description adds meaningful behavioral detail: it explains the paired debit/credit effect and that Ready to Assign remains unchanged. It also discloses rollback behavior if the second change is rejected, which is valuable for a destructive mutation.

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 tightly structured across three short sentences, with the core operation front-loaded. Each sentence contributes useful information: purpose, effect, and failure behavior.

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 output schema and annotations, the description covers the important behavioral context an agent needs: category-to-category movement, no Ready to Assign change, and rollback on failure. Nothing essential for correct invocation is missing.

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 parameter descriptions already carry the main semantics for month, amount, and category IDs. The tool description reinforces the direction of the amount movement, but does not add substantial syntax or format 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 states a specific verb and resource: moving assigned money from one category to another within a month. It also clarifies that Ready to Assign does not change, which distinguishes this operation from assign_money or set_assigned even without naming them directly.

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 gives clear use cases: covering overspending or reallocating between categories. However, it does not explicitly state when not to use it or name alternative tools such as assign_money, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds no additional context—no mention of the destructive effect on transactions or budgets referencing the group, no length/validation notes beyond the schema, and no return behavior.

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

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

The single sentence is concise and front-loaded with the action, but it is under-specified rather than efficiently minimal. There is no wasted wording, but there is also almost no 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?

For a destructive, idempotent mutation tool, the description should disclose consequences (e.g., effect on existing category references) and any constraints. With an output schema present, return values need not be explained, but the behavioral side is essentially absent.

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 documented including the 50-character limit and UUID format, so the baseline is 3. The description adds nothing beyond the schema, but it doesn't need to.

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 'Rename a category group.' only restates the tool name and title, making it a tautology under the rubric. It does identify the verb (rename) and resource (category group), but gives no scope or distinction from related siblings like rename_payee or update_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?

No guidance on when to use this tool versus alternatives such as create_category_group or update_category, and no preconditions are stated. The agent must infer usage entirely from the name.

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 flag destructiveHint=true and idempotentHint=true, so the risk profile is covered. The description adds genuinely useful blast-radius context that annotations cannot convey: the rename propagates to every transaction with that payee. It stops short of saying whether the rename is reversible or what permissions are needed, but the key behavioral consequence is disclosed.

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, zero filler, with the core action first and the side effect second. Nothing could be removed without losing 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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The one remaining gap is the absence of any guidance on prerequisites or error conditions, though for a two-parameter rename the description is otherwise sufficient.

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 payee_id and name are fully documented in the schema, including the 500-character limit. The description adds no parameter-level detail beyond implying that name is the field reflected in transactions, so the baseline 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?

A specific verb ('Rename') and resource ('payee') stated up front, cleanly separated from siblings like create_payee, list_payees, and find_payee. The second sentence clarifies the scope of the operation, so an agent knows exactly what changes.

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 never says when to use this versus create_payee or find_payee, nor does it state preconditions (does the payee need to exist, does it require an ID first?). The propagation note hints at consequences but gives no decision 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?

Annotations already declare idempotentHint=true and destructiveHint=true; the description earns extra credit by explaining WHY it is retryable (overwrite semantics) and by disclosing a non-obvious side effect: 'Ready to Assign absorbs the difference'. That budget-side effect is not derivable from the schema or annotations and is the kind of context an agent needs before mutating a budget.

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 short sentences, front-loaded with what it does, then the sibling contrast, then the side effect. No restated field lists and nothing extraneous; the retry note is brief and functional rather than padding.

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 3-parameter mutation with an output schema and rich annotations, the description covers the differentiating semantics and the Ready to Assign side effect, which is the main hidden behavior. Minor gaps (e.g., behavior with negative or non-numeric amounts, interaction with existing over-allocations) remain but are not blocking.

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%, including the month enum/date union and the amount/category semantics, so the schema does the heavy lifting. The description adds only the notion that amount is the new total rather than a delta, which is already implied by 'new assigned amount' in the schema. Baseline 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?

States a specific verb and resource (set the assigned amount for a category in a month) with explicit scope. It also names the sibling it is not (assign_money) and the exact behavioral difference, so an agent can distinguish the two without opening either schema.

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 contrasts with assign_money ('this replaces the assigned amount') and gives a decision-relevant property (safe to retry). It stops short of a positive rule for when assign_money is the better choice, but the replacement-vs-adjustment distinction is clear enough for 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 destructiveHint=true and idempotentHint=true; the description usefully mitigates the destructive concern by stating 'Only the fields given change,' i.e. PATCH-style partial semantics, so the agent knows omitted fields are not wiped. It does not disclose permission requirements or what happens when a target is unset/null-passed, which matters given the destructive flag.

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 filler. The capability list and the partial-update guarantee are front-loaded before the alternative-routing sentence, so the most decision-relevant information comes first.

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 an 8-parameter mutation with annotations and an output schema, the description covers what can change and the non-destructive-by-default field scoping. It omits edge behavior an agent might need — clearing an existing target, permission/auth expectations, and effects of target changes on budgeting — but the schema covers the parameter-level detail.

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 every one of the 8 parameters (including the target_date/target_frequency conflict and target_frequency requiring target_amount) is already documented in the schema. The description only restates the field groups at a high level and leaves the key ambiguity unresolved: whether passing null clears a field versus omitting it. 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?

States a specific verb (update) plus the resource and enumerates exactly the updateable facets: rename, note, group move, target. It also explicitly names the adjacent capabilities handled elsewhere (assign_money, set_assigned), so an agent can separate this tool from siblings that also sound like 'changing a 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?

Provides a clear routing rule for the most likely confusion: 'To change what is assigned to a category, use assign_money or set_assigned.' That is a genuine when-not clause naming alternatives. It does not cover other nearby cases (e.g., when to use create_category vs. this tool, or renaming a group via rename_category_group), so it stops short of fully explicit routing.

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 this operation destructive and idempotent. The description adds meaningful behavioral context beyond annotations: omitted fields remain unchanged, and split scheduled transactions cannot be updated. It does not explain the practical consequences of the destructive update, but the annotation covers the safety profile.

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 short sentences, front-loaded with the core action and partial-update rule, followed by usage scenarios and a key API limitation. Every sentence adds useful information without 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 an 11-parameter mutation tool with full schema descriptions, an output schema, and annotations covering safety behavior, the description provides enough context: what the tool changes, how omitted fields behave, when to use it, and a critical unsupported case.

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

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

Schema description coverage is 100%, so the schema carries most parameter details. The description adds the important partial-update semantic ('Fields left out do not change'), which is not explicit in the schema and affects how all optional parameters should be interpreted.

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 and resource ('Change a scheduled transaction') and immediately distinguishes the operation from create/delete/enter sibling tools by naming the exact change scenarios: amount, day, account, or recurrence schedule.

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 gives clear when-to-use guidance ('when a bill's amount changes, it moves to another day or account, or it repeats on a new schedule') and one important exclusion (split scheduled transactions cannot be changed). It stops short of explicitly naming alternative sibling tools to use when this tool does not apply.

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 annotations, the description discloses partial-update behavior ('only the fields to change; every other field stays as it is') and batch semantics ('one or more existing transactions in one request'). It does not explain atomicity, failure behavior, or permission requirements, but the annotations already carry destructive, idempotent, and readOnly hints.

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 definition is front-loaded with the core operation, then adds compact examples. The sentences and bullets are information-dense without being bloated.

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 full schema coverage, an output schema, and rich annotations, the description covers batch updates, partial updates, and common update scenarios. Missing atomicity or error-handling details are minor for this tool because structured fields already cover return and safety semantics.

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

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

Schema description coverage is 100%, so the schema already documents every field, default, enum, and update constraint. The description's example changes reinforce usage but add little semantic detail beyond what the schema already provides, fitting the baseline 3 for high-coverage schemas.

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 opens with a specific verb and resource: 'Change one or more existing transactions in one request.' It scopes the operation to existing transactions and names concrete update types, making it distinguishable from create/delete transaction 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?

It clearly states this is the tool for reviewing transactions and lists approve, categorize, fix payees, set memos, flag, and mark cleared. It does not explicitly name when not to use it or point to sibling alternatives, but the intended usage context is strong.

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