YABA family budget

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

Annotations already declare idempotentHint=true, but the description earns credit by explaining the mechanism: the caller must supply its own UUID as id so that a repeat call is a no-op. That operational detail is not derivable from the annotation alone. It still omits auth/permission requirements and what the call returns.

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

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

Five compact sentences, front-loaded with purpose and then ordered by importance: idempotency, argument requirements, amount units, date formats. Almost every sentence earns its place, though the trailing 'month is a budget period YYYY-MM' clause is irrelevant to this tool's schema and adds noise.

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 13-parameter mutation tool with no output schema and no field-level schema descriptions, the description covers the critical semantics but leaves the multi-currency transfer fields (toAmount, toCurrency, baseAmount) and currency/isRefund/note unexplained. Adequate for a simple expense call, but incomplete for the transfer and multi-currency cases the tool explicitly supports.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it compensates well for the highest-risk fields: amount unit convention (integer minor units, 45000 = 450.00), the idempotency key id, conditional categoryId/toAccountId, and the YYYY-MM-DD date format. However, roughly half the parameters (note, currency, isRefund, toAmount, baseAmount, toCurrency) remain undocumented, and the stray 'YYYY-MM budget period' remark has no corresponding schema parameter, which is mildly confusing.

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 ('Add an expense, income or transfer') and enumerates the three record types the tool accepts, which immediately distinguishes it from update_transaction, bulk_update_transactions and delete_transaction. An agent can identify the tool without opening 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 explicit conditional requirements that guide invocation: categoryId is required for expenses and income, transfers need toAccountId, and it routes to list_categories to obtain a categoryId. It does not explicitly contrast with update_transaction or bulk_update_transactions, but the conditional argument rules provide clear usage context.

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

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

Annotations already declare the operation is a non-readOnly, non-idempotent, non-destructive write, so the bar is lower. The description goes well beyond them: it discloses the side effect on the goal's amount, the automatic month-selection behavior, and the exact return value ('the plans it replaced (before)') for undo — valuable since there is no output 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?

Front-loaded with the core action, then unit/format rules, then return value. Three dense sentences carry a lot of information without filler, though the format details could be tighter and the sentence order slightly buries the undo guidance.

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 two-parameter mutation with no output schema, the description covers the side effects, return shape, currency units, and month semantics. Remaining gaps are the unspecified 'id'/'categoryId' meaning and explicit non-idempotent behavior, which are minor against the otherwise complete picture.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain 'amount' precisely (integer minor units, 45000 = 450.00) and the date/month format, but says nothing about the required 'id' parameter (presumably a goal id) or the 'categoryId' field, leaving half the semantics undocumented.

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 with its effect: it lowers categories' plans by given amounts and adds the total to the goal's monthly amount. This is clear enough to distinguish it from set_budget/update_goal, though it never names those siblings explicitly as the lower-level alternative. A reader understands what the tool does, but the phrasing is dense.

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 implicit usage context by naming set_budget and update_goal as the tools to reverse the operation, and by specifying the 'first budget month that still gets money in' selection rule. However, it never states when to prefer this over set_budget/update_goal for the forward operation, nor any preconditions or exclusions.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is partly covered. The description adds genuinely non-obvious behavior: the 100-item cap and, critically, that deletes are 'restorable for 30 days' – context an agent cannot get from 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?

A single dense sentence leads with the core action and cap, then the action branches, then format details. Every clause earns its place except the amount-format note, which is irrelevant to this schema.

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 no output schema and 0% schema coverage, the description supplies the limit, the restore window, the action branches and date/format conventions. Only the ids parameter semantics remain unexplained.

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 0%, so the description must carry parameter meaning. It maps the patch fields (category, account, date, note) and the edit/delete action, and explains date syntax 'YYYY-MM-DD' plus the YYYY-MM budget month. But it also documents 'amounts' as minor units, which is not a parameter of this tool, and says nothing about the ids array beyond the count.

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?

Specific verb+resource with scope: 'set their category, account, date or note (edit), or delete them' for 'up to 100 entries at once'. The bulk scope implicitly distinguishes it from the single-item siblings update_transaction and delete_transaction, though neither is named.

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

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

Usage is implied by the 'up to 100 entries at once' framing, letting an agent infer this is for batch operations, and the edit-vs-delete branches are stated. However there is no explicit guidance on when to prefer bulk over single-item siblings or on prerequisites.

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 safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds the copy-source behavior and format conventions but never clarifies whether existing plan entries are overwritten or merged, which is important for a 'fill' 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?

Three compact sentences, front-loaded with the core purpose. The minor-units/date-format sentence is somewhat tangential since neither parameter is an amount, but it is brief and still useful for interpreting copied values.

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

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

For a simple two-parameter mutation tool with no output schema, the description covers purpose and value formats. The notable gap is overwrite/merge semantics on the destination month, which an agent needs to call it safely.

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

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

Schema description coverage is 0%, so the description must carry the load. It explains 'kind' (expense or income) and clarifies 'period' as a YYYY-MM budget period, which meaningfully documents both parameters. It leaves some ambiguity about whether 'period' is the target month being filled.

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+resource+source: 'Fill a budget month's plan (expense or income) from the month before.' An agent can immediately grasp the copy-forward operation. However, it does not name a sibling (e.g., set_budget) to differentiate from, 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 gives no when-to-use or when-not-to-use guidance and does not mention alternatives such as set_budget. The only hint is the implicit source ('from the month before'), which describes mechanics rather than decision context.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the description only needs to add context. It adds the joint-account rule (ownerId null) and unit/date conventions, but the amount and date formatting notes do not correspond to any parameter of this tool, and it says nothing about what happens on success or about duplicate names.

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 and the text is short, but roughly half of it (integer minor units, YYYY-MM-DD, budget period YYYY-MM) is irrelevant to a tool whose parameters are name, kind, icon, color, ownerId, and currencies. That boilerplate does not earn its place.

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

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

With 6 parameters, 0% schema description coverage, and no output schema, the description should do more: it never states the result of creation, whether the name must be unique, or the expected currency-code form, even though enum-valued fields (icon, color, kind) are self-documenting.

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

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

Schema description coverage is 0%, so the description has to carry the load, and it only clarifies ownerId ('null = joint') plus examples of kind. It leaves name, icon, color, and the currency-code format for 'currencies' unexplained, and the minor-unit/date guidance it does give maps to no parameter here.

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 an account ... with its currencies') and enumerates the account kinds (cash, card, savings...), so the agent immediately knows what is produced. It is implicitly separable from update_account/list_accounts by the verb, but the description itself does not call out any sibling or contrast, keeping it 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?

There is no when-to-use or when-not-to-use guidance: nothing says whether an account must already exist, when to prefer set_balance or update_account instead, or what preconditions (family membership, unique name) apply. Usage is only inferable from the verb 'Create'.

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 safety profile is covered. The description adds genuinely useful behavior context — names must be unique per kind — which explains the non-idempotent nature and an expected failure mode. It still omits what happens on a duplicate name, permission requirements, or defaults applied to omitted color/icon.

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 correctly front-loaded, but roughly half the text is boilerplate about amounts in minor units and date/month formats that are irrelevant to create_category's schema. That content earns no place here and dilutes the useful uniqueness note.

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 four-parameter creation tool with no output schema, the description should at minimum cover the required fields, the optional enum fields, defaults, and duplicate-name behavior. Instead it covers the required fields only partially and spends its remaining budget on amount/date conventions that belong to add_transaction or set_budget.

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

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

Schema description coverage is 0% for four parameters, so the description must carry the load. It clarifies only two: that kind is expense-or-income and that name is unique per kind. It says nothing about icon or color (the latter having a 16-value enum), and the amount/date sentences describe parameters that do not exist on this tool, actively adding noise.

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 opening clause states a specific verb and resource ('Create an expense or income category') and adds the uniqueness constraint per kind, so the agent knows exactly what object is produced. It does not explicitly contrast itself with create_account/create_goal or with update_category, so it falls short of full sibling 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?

There is no guidance on when to create a new category versus reusing one via list_categories or renaming via update_category, and no mention that name and kind are required while icon/color are optional. Usage is only implicitly derivable from the verb.

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-readOnly, non-idempotent, non-destructive write, so the bar is lower. The description still adds real behavioral context beyond annotations: balance-sharing priority order when goals share an account, the free-plan active-goal cap, and when targets are auto-computed. It does not state permission/authorization requirements.

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?

Information-dense and largely waste-free, with the core action stated first followed by per-kind rules. The long semicolon-chained sentences make it dense rather than elegantly structured, but each clause carries needed semantics.

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 10-parameter mutation tool with no output schema and zero schema-description coverage, the description covers the high-risk semantics well (kinds, targets, units, dates) but leaves multiple parameters unexplained, notably the monthly contribution field. An agent would still lack guidance on several inputs.

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

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

Schema description coverage is 0% across 10 parameters, so the description must carry the load. It explains kind semantics, months values, target computation, minor-unit integers, and date/month formats, which is valuable. However, several parameters (monthly, color, icon, name, accountId, currency) get no explanation at all, so compensation is only partial.

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 goal on an account') and then enumerates the three distinct kinds (save, emergency, debt) with their distinct semantics. This clearly separates it from siblings such as update_goal, list_goals and delete_goal.

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 strong conditional guidance: which account types each kind may attach to ('never a card or cash'), when target may be omitted ('target computed when left out'), and the free-plan limit of one active goal. It does not explicitly contrast with sibling tools (e.g. update_goal vs create_goal), so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable context beyond annotations: deleting a goal leaves its account and money untouched because a goal holds no entries. It doesn't cover auth requirements or rate limits, but with annotations covering the safety profile this is sufficient.

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 first three sentences are front-loaded and relevant: purpose, consequence, and alternative. The final two sentences about minor units and date formats are irrelevant to a delete operation that takes only an id, wasting space and potentially confusing the agent.

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 destructive delete tool with no output schema, the description covers purpose, consequence, and alternative. However, it omits the meaning of the only parameter and pads with unrelated conventions. An agent still has to infer that 'id' is the goal identifier, leaving a clear 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 0% and the only parameter 'id' is never mentioned in the description. The sentences about integer amounts and date formats refer to fields this tool does not accept, so they add no meaning to the sole parameter. The agent must infer that 'id' identifies the goal.

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: 'Delete a goal.' This clearly distinguishes it from sibling tools like update_goal or delete_transaction. An agent can identify the operation without opening 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?

It explicitly recommends the alternative: 'Prefer archived: true in update_goal to keep it.' This tells the agent when to use update_goal instead of delete_goal. The condition for choosing deletion (permanent removal) is clearly implied.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond that: the 30-day restorability window and the restore tool to use. It does not mention permission requirements or side effects on related records (e.g., balances or budgets).

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 and restore-window sentences are front-loaded and earn their place. The trailing amount/date/period formatting rules are boilerplate irrelevant to a single-id delete call and dilute the definition.

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 one-parameter destructive delete with no output schema and full annotation coverage, the reversibility disclosure is the key missing piece and it is present. Still absent: any description of the id's expected format, and whether deleting cascades to related data.

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

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

Schema description coverage is 0% and the single parameter (id) is undocumented in both schema and description. Worse, the description spends its parameter-level text on amount-in-minor-units and date-format conventions that do not correspond to any parameter this tool accepts, so it adds no usable meaning for id.

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 an entry") that matches the tool name delete_transaction, so an agent knows exactly what operation runs. It does not contrast itself with the other write siblings (bulk_update_transactions, update_transaction), but the intent 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?

Gives clear operational context by naming the recovery alternative (restore_transactions) and its 30-day window, which tells the agent this is recoverable rather than permanent. It stops short of stating exclusions or when a bulk/alternative delete path should be preferred.

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

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

Annotations declare a non-read-only, idempotent, non-destructive mutation, so the safety profile is partly covered. The description adds that the key originates from list_bills, but does not state whether the change is reversible (undismiss_bill exists), what happens to the payment record, or any effect on budgets. Modest added value, no contradiction.

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

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

The first sentence is well front-loaded, but the following two sentences about integer minor units and YYYY-MM-DD/YYYY-MM date conventions do not apply to a tool with only a 'key' parameter. Roughly two-thirds of the description is irrelevant boilerplate, diluting the useful 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?

No output schema exists, so the description should explain the effect of the operation, but it stops at identifying the key source. For an idempotent mutation it omits reversibility, side effects, and prerequisite context. Adequate to invoke, incomplete for understanding consequences.

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 sole parameter 'key' has 0% schema description coverage, so the description must carry the burden. It does add that the key comes from list_bills, which is useful, but then spends its length on amount units and date formats that are irrelevant to this tool's single string parameter. Format expectations for the key itself remain undefined.

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 action (marking a found regular payment as not-a-bill) and identifies the resource via the key from list_bills. The sibling undismiss_bill provides the inverse, but the description never names or differentiates against it, and the title 'Not a bill' is cryptic. Purpose is clear enough to act on without opening 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?

Points the agent at list_bills as the source of the key, which implies the workflow, but gives no explicit when-to-use, when-not-to-use, or alternative (e.g. undismiss_bill is never mentioned). Usage is inferred rather than 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description usefully goes beyond that by specifying units (integer minor units, 45000 = 450.00) and date/time-zone semantics, which is genuine added value. However it says nothing about return shape, grouping cardinality, or whether ranges are inclusive, so it only partially carries the load left by the missing output 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?

It is compact at three clauses, but poorly front-loaded: the opening fragment 'A year by budget month and category: expenses and income' has no verb and reads as a noun phrase, so the reader must reconstruct what the tool actually does. The unit and date notes are dense but 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 one optional parameter and no output schema, an agent most needs to know what comes back; the description only hints at 'by budget month and category' and gives no structure, pagination, or empty-result behavior. The unit and time-zone conventions are valuable, but the picture is still incomplete.

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

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

Schema coverage is 0% for the single 'year' parameter, so the description must compensate. It clarifies 'YYYY' formatting and the meaning of a budget period (YYYY-MM, the period starting in that month), which adds real semantics, but it never says whether the year is optional, whether it defaults to the current year, or how calendar vs. budget-year boundaries are treated.

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 gestures at an aggregation of expenses and income by budget month and category for a year, but it never states a verb or the retrieval action ('returns yearly expense/income totals grouped by budget month and category'). It also does not distinguish this from close siblings like get_overview, get_budget, or get_retrospective, so an agent must guess which aggregate report to pick.

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 prerequisites, and no named alternative tool. With siblings get_overview, get_budget, get_retrospective, get_balances all returning summaries, the absence of routing guidance is a real gap.

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 the safe read profile (readOnly, idempotent, non-destructive, closed-world), so the burden is lower. The description adds genuinely useful behavioural context beyond them: amounts are integers in minor units (45000 = 450.00) and dates follow the family time zone with YYYY-MM budget periods.

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, each carrying non-redundant information, with the core output (balances per currency and base total) front-loaded. Slightly packed with formatting rules, but 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 no output schema and no parameters, the description must carry the return-value burden, and it does explain the currency breakdown, base-currency total, rates, minor-unit amounts and date conventions. It could still state whether all accounts or only non-zero ones are returned, but coverage is otherwise solid for a simple read tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter detail and instead spends its space on output-value conventions.

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 the concrete resource and its contents: each account's balance per currency, a total in the base currency, and today's rates. That is specific enough to distinguish it from set_balance or list_accounts, though it never uses a verb and does not explicitly differentiate itself from near-neighbours like get_overview or get_analytics.

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

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

There is no statement of when to call this tool versus the many siblings (get_overview, get_analytics, list_accounts, set_balance). The formatting conventions hint at what the tool returns but give no routing or 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, idempotentHint and non-destructive, so the safety profile is covered. The description usefully adds unit and date conventions, but omits behavior for the optional period argument (what happens when it is omitted) and any error/edge 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?

Front-loads what the tool returns, then follows with the two format conventions an agent needs. Compact and free of filler, though the units/dates sentence is dense enough that it could be split for scanability.

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

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

With no output schema, the description carries the burden of describing the return shape and does so reasonably (plan, spent, average, pace, expenses, income). The remaining gap is the undefined fallback when period is omitted.

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 0%, so the description must compensate. It does explain the period format well ('a month is a budget period YYYY-MM, the one that starts in that month') and the minor-unit convention, but leaves the default behavior for the optional period unspecified.

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 resource and its contents concretely: a budget month's per-category plan with spent amounts, a 12-month average and pace, plus expenses and income. Clear what the tool returns, but it never distinguishes itself from close siblings like get_overview, get_analytics or get_goal_plan.

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 and no alternative named. An agent cannot tell from the description when to call get_budget versus get_overview or get_analytics, nor when a non-current period is appropriate.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine value beyond them by disclosing the payload's contents and the unit/date conventions needed to interpret the values, which matters since there is no output 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?

Front-loaded with the resource and its fields, then a compact two-sentence conventions note. Nothing is padded, though the amounts-in-minor-units rule is only loosely relevant to a family object that exposes no amounts, so a small slice of the text is tangential.

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

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

For a zero-parameter, read-only getter with no output schema, the description carries the burden of describing the return and does so by listing the family's fields and the formats its values use. It stops short of detailing member structure or an id field, but is adequate for correct invocation.

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

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

The tool takes zero parameters, so the baseline is 4. There are no inputs whose semantics need explaining, and the description correctly spends no words on parameters.

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

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

The description identifies a specific resource — the family this connection is for — and enumerates its fields (name, base currency, budget month start day, time zone, member names), so an agent knows exactly what it returns. It does not explicitly name or distinguish itself from siblings like get_overview or get_budget, but no sibling competes for the 'family' resource.

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

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

There is no when-to-use statement, no prerequisites, and no reference to alternatives. The remaining sentences describe data conventions (minor units, date/month formats) rather than guidance on when this tool is the right call, so an agent must infer the trigger condition.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered; 'Changes nothing' merely restates it. The description adds useful conventions (minor units, date/month formats) but says nothing about what the computed plan actually contains or how projections are shaped.

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?

Dense but front-loaded: the core scenario is stated first, followed by encoding conventions. Every clause carries information, though the parenthetical stacking makes it slightly hard to parse on first read.

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

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

With no output schema, the description should describe what the plan returns (projection shape, dates, currency handling), and it does not. Input semantics are well covered, but for a simulation tool whose entire value is the returned plan, the return side is a real 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 0%, so the description must compensate, and it largely does: it explains that cuts takes categoryId and a per-month amount in base currency, monthly is a per-month amount in goal currency, and last is a budget month. It also documents the integer/minor-unit and YYYY-MM/YYYY-MM-DD encoding conventions. The required 'id' parameter is left implicit, keeping it from a 5.

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 resource (a goal's plan) and clearly frames it as a hypothetical/what-if computation over three scenario levers (cuts, monthly, last). The title 'What if' plus 'Changes nothing' signals it is a simulation rather than a mutation, distinguishing it from apply_goal_cuts. It stops short of explicitly naming that sibling, so differentiation is inferential.

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 implies simulation use ('a goal's plan if...' and 'Changes nothing') but never states when to reach for this versus list_goals, update_goal, or apply_goal_cuts. No prerequisites or when-not guidance is given, so the agent must infer that this is the preview step before actually applying cuts.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely useful context the annotations cannot: amounts are integers in minor units (45000 = 450.00), dates are YYYY-MM-DD in the family time zone, and a month means a budget period. It does not describe response shape, though no output schema exists.

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: the first front-loads the returned content, the second packs the unit/format conventions. Dense but no filler; the only weakness is the list-like phrasing without a leading verb.

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

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

With no output schema and a single optional parameter, the description carries the return-value burden and does so by naming each section of the overview plus the numeric and date encoding. Missing only the response structure and the fact that read-only aggregation has no side effects beyond what annotations say.

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 already states the YYYY-MM pattern and default of the current budget month. The description clarifies that a month is a budget period 'the one that starts in that month' and that dates use the family time zone, which adds some meaning, but no further parameter detail.

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 enumerates exactly what the tool returns — spent/planned amounts, per-category pace, month-end forecast, income, upcoming bills — so the agent knows it is a read-only month-level summary. It never names the sibling read tools (get_analytics, get_budget, get_balances, get_retrospective), so the agent cannot tell which summary to pick from the description 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 statement of when to use this versus get_analytics, get_budget, or get_balances, which all sound like overlapping read summaries. The only implicit cue is '(or another)' month via the period parameter.

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, idempotent, non-destructive behavior, so the bar is lower, and the description adds real context beyond them: a default of 6 months, valid month windows (3/6/9/12), integer minor units with an example, and the family-timezone budget-period definition. It does not describe the response shape, but with no output schema that is a modest gap against an otherwise informative 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 units/dates/periods sentence is dense but every clause pays off, and the drill-down condition is front-loaded. The metaphorical opener ('family portrait') and the vague title cost clarity without adding information, and the whole thing is delivered as one long block rather than clearly separated concerns.

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 read-only summary with no output schema, the description covers the important mechanics an agent needs: default window, allowed months, unit and date conventions, and the two modes (aggregate vs. drill-down). The remaining gap is the absence of any hint about the returned structure, which matters somewhat given no output schema exists.

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 0%, so the description must carry the load, and it does: months is constrained to 3/6/9/12 with default 6, key is described as 'a bill', and categoryId/irregular are described as selecting the entries behind a single number. That compensates well for the undocumented schema, though it doesn't state what happens if multiple selectors are combined.

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 says it produces a multi-month retrospective covering committed bills, spending, income, leftover, changes and habits, which conveys the resource. But the framing ('family portrait', title 'The usual month') is metaphorical rather than a clean verb+resource, and it never distinguishes itself from siblings like get_analytics, get_overview, or get_budget that an agent must choose between.

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 conditional usage for the drill-down path ('With key (a bill), categoryId or irregular: the entries behind that one number'), which is genuinely helpful. However it never states when to prefer this tool over get_analytics/get_overview/get_budget, so the primary routing decision is left to inference.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-obvious domain semantics: amounts are integers in minor units (45000 = 450.00) and dates/months use family-time-zone conventions, which an agent needs to interpret what comes back. It does not cover behavior for a missing or invalid 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, front-loaded sentences with no filler; the retrieval clause comes first and the format conventions follow. Slightly odd that most of the text is about return-value formatting rather than the operation itself.

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

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

With no output schema, the description is the only place return information can live, and it explains value units and date formats but never describes the entry's fields, structure, or what happens when the id is not found. Partial compensation for the missing 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 0% for the single required `id` parameter, but the parameter is self-describing (a string id) and the description only restates that the lookup is "by its id". No format hints are added beyond what the schema name/type already 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?

"One entry by its id" implies a single-record fetch, but the resource is called an "entry" rather than a transaction and no retrieval verb is used, so the reader has to infer the operation from the sibling list. It distinguishes single-fetch from list_transactions only weakly, and leans on the title ("One entry") for meaning.

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 about when to use this tool versus list_transactions, get_analytics, or any other read sibling, and no mention of prerequisites or failure conditions. Only the implicit "by its id" signals single-record retrieval.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds genuinely useful interpretive context (integer minor units, YYYY-MM-DD / YYYY-MM conventions) but says nothing about what the response contains, whether archived accounts are included, or ordering.

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?

Short and dense: a field fragment followed by two convention sentences, with no filler or repetition. The format rules earn their place given there is no output schema to document units and date formats.

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

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

With no parameters and no output schema, the description is the only channel for return-value semantics, and it covers field names, amount units and date formats. It still leaves gaps an agent would care about: whether archived accounts appear in the result, what the default ordering is, and how the 'owner = null means joint' rule should be interpreted in output.

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 and there is no parameter meaning for the description to supply. Nothing in the text contradicts 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?

The resource is unmistakable ('Accounts: kind, currencies, owner..., archived'), but the description never states a verb or what the tool does with it. An agent can infer a listing from the name, but the text itself is a field glossary rather than a purpose statement and does nothing to distinguish this from siblings like get_balances or list_categories.

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 alternatives (e.g. get_balances for totals, list_categories for the category tree), and no stated prerequisites or scoping. The agent must infer everything 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context that annotations cannot carry: amount units (minor units, 45000 = 450.00), date format and the family time zone, and what a 'month' means (budget period YYYY-MM). It stops short of describing volume, ordering, or pagination.

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, with the returned-field inventory front-loaded and format rules consolidated into a second sentence. The opening clause is slightly run-on and the 'YABA found or someone marked' phrasing costs a moment of parsing, but 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 no output schema and no input parameters, the description carries the full documentation burden and does so: it lists the returned fields, explains the units and date/time-zone conventions, and points at the follow-up tools that consume the key. Missing only ordering/pagination and the exact shape of the key field, which are minor for this tool.

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

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

The tool takes zero parameters, so the baseline is 4. The description compensates by documenting the value formats an agent needs to interpret results (minor-unit amounts, YYYY-MM-DD dates, YYYY-MM budget periods), which is the relevant semantic detail for a no-arg list tool.

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

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

The description enumerates what the tool returns (recurring payments and income, detected automatically or manually marked) and the fields each entry carries, so an agent can infer it is a read/list tool for recurring bills. It lacks a clean verb+resource opener (the name 'list_bills' isn't restated, and 'YABA found or someone marked' is grammatically murky), but the resource is unambiguous and it distinguishes itself from siblings by naming the key consumed by dismiss_bill/unmark_bill.

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 only implied: the mention of 'the key to use with dismiss_bill / unmark_bill' signals this is the discovery step before those mutation tools, but there is no explicit when-to-use statement, no exclusions, and no comparison against sibling list/mark tools like list_transactions or mark_bill.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: archived categories are still returned but flagged, which an agent could not learn from the schema or annotations.

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

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

The resource identification is front-loaded and the sentences are compact, but a large share of the text covers amount units, date formats, and budget-period semantics that are irrelevant to a no-parameter category listing, making the content feel borrowed from a sibling tool.

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

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

With no output schema and no parameters, the description carries the full burden of describing the return value, yet it never says what a category contains (id, name, parent, type, archived flag) or the response shape. The format notes are generic rather than category-specific, so the definition is only partially complete.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter documentation, though its amount/date conventions are not parameters of this tool.

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

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

The description names the resource ('expense and income categories') and notes archived ones are flagged, but never states a verb or that it returns the list — the 'list' action is only inferable from the tool name. It also does not distinguish itself from siblings like create_category, update_category, or list_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 condition selecting this tool over create_category/update_category, and no note about prerequisites such as needing a family context. The description is purely a data-format glossary, leaving usage entirely to inference.

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 cover the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description earns credit for adding substantive semantics: null 'room' meaning insufficient history, enumerable status values, minor-unit encoding, and date/month formats. It stops short of any auth, permission, or rate-limit context, so it is not exhaustive.

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?

It is a single dense sentence with essentially no wasted clauses — units, date formats, statuses, and the null case all carry information. Front-loaded with the purpose, but the deeply nested parentheticals make it harder to parse than a structured list would be.

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

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

With no output schema, the description carries the return contract and does so thoroughly (room, saved, target, monthly need, amount, done date, status, suggested cuts). The one soft spot is the suggested spending cuts, whose structure is only gestured at ('cuts that would make it'), leaving an agent to infer its shape.

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 instead invests its detail in return-value semantics (units, date formats, statuses), which is appropriate for a parameterless list call.

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 'The family's goals in priority order with their plans,' which clearly identifies the resource and scope (all goals, ordered, with plans). However, it never names or distinguishes itself from the sibling get_goal_plan, and it is phrased as a return-value spec rather than an explicit 'list X' statement, so an agent gets the purpose but not the sibling routing.

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 exclusions, and no mention of alternatives such as get_goal_plan (single goal detail) or apply_goal_cuts (acting on the suggested cuts). Usage is only implied by the read-only listing content.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioural detail beyond that: ordering semantics ('newest first, or biggest first'), pagination ('Pages of up to 200: pass nextCursor back as cursor'), and the minor-unit convention for amounts — all useful for correct invocation.

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 dense paragraph that front-loads purpose and ordering before filters, pagination, and unit conventions. Every clause carries information, though the run-on construction packs date/period/unit rules tightly enough that it reads more like a spec note than a description.

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

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

With 11 parameters, no required fields, and no output schema, the description supplies the essentials an agent needs: sort meaning, filter axes, pagination protocol, and numeric/date encoding. It is complete enough to call correctly; only the lack of explicit param-name-to-concept mapping leaves a small 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 only 9%, so the description must carry the load, and it largely does: it explains amount units (45000 = 450.00), date format and time zone, that a month is a budget period YYYY-MM, and what sort's two values mean. It stops short of explicitly mapping every param name (memberId, accountIds, categoryIds, limit are only alluded to as 'member', 'accounts', 'categories', 'pages of up to 200').

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 with its domain shape: 'Entries (expenses, income, transfers) newest first, or biggest first.' An agent can immediately distinguish this listing tool from get_transaction, add_transaction, and the other list_* siblings without opening any 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?

The description enumerates filter axes (month/dates, type, note text, accounts, categories, member), which implies when the tool is useful, but it never names an alternative or states when NOT to use it (e.g., use get_transaction for a single entry). Usage is inferable rather than 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=false, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact ('YABA never adds entries by itself'), which prevents a wrong assumption that marking creates transactions. It stops there, saying nothing about what marking actually changes (e.g. recurring plans or budget projections).

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 leading sentence is well front-loaded and the 'never adds entries' caveat earns its place. But two of the three sentences discuss amount minor-units and date formats for parameters that do not exist in this schema, so a substantial portion of the text is irrelevant noise for this tool.

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 mutating tool with three params (only cadence required) and no output schema, key details are missing: the txId/categoryId combination rule is unstated (the schema permits both or neither), and the relationship to unmark_bill is absent. An agent could invoke it, but could easily pick the wrong target combination.

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

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

Schema description coverage is 0%, so the description must carry the load. It does clarify txId as an entry's payee and categoryId as a whole category, and the cadence enum values are self-explanatory. However, it never resolves whether txId and categoryId are mutually exclusive or that at least one is expected, and the amount/date formatting text maps to no parameter in this 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 concrete action and its two modes: marking a single entry's payee (txId) or a whole category (categoryId) as a regular payment at a cadence. It adds the caveat that YABA never adds entries itself, which implicitly separates this from add_transaction. It does not name-mark against unmark_bill or dismiss_bill, so it stops short of full sibling 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?

No when-to-use or when-not guidance is given. The inverse tool unmark_bill and the nearby dismiss_bill/list_bills are never referenced, so an agent has no stated basis for choosing this over them. The 'YABA never adds entries' line is a behavioral note, not usage 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 establish that this is a non-destructive, idempotent write. The description adds nothing about the mutation's scope — notably whether goals omitted from ids are removed from the ordering or appended after those listed, which is the central behavioral question for a reorder operation.

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

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

The ordering rule is correctly front-loaded, but two of the three sentences are boilerplate about minor-unit amounts and YYYY-MM budget periods — quantities and dates that do not exist in this tool's single parameter. That content doesn't earn its place here and dilutes the actionable instruction.

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 param, annotations covering safety), and the description conveys the ordering contract. What is missing is the effect on goals not present in ids and whether the supplied list must be exhaustive, which an agent needs to call this correctly.

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

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

With 0% schema description coverage, the description must carry the load. It does supply the essential semantic that the array order encodes priority ('first = most important', 'room goes down the list'), which the schema cannot express. However, it wastes that space on amount and date formatting rules that have no corresponding parameters in this 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 clause states a specific verb and resource — 'Put goals in priority order' — which clearly distinguishes it from create_goal, update_goal and list_goals. It doesn't explicitly name an alternative tool, but the operation 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 update_goal or apply_goal_cuts, and no prerequisite or state requirements (e.g. must all goals be listed?). The only usage-adjacent content is the ordering convention, which is a parameter semantic rather than invocation 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 declare this is a write (readOnlyHint=false) that is non-destructive and non-idempotent, so the agent already knows the safety profile. The description usefully states the 100-id batch limit, but says nothing about permissions, whether a restore is reversible, or partial-failure behavior — and its currency/budget-period sentences concern parameters this tool does not have.

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 and the 100-id constraint are front-loaded and efficient, but two of the three sentences are about amount and date formats that have no corresponding parameters here, so real estate is spent on irrelevant boilerplate.

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 one-parameter mutation tool with no output schema, the description covers the core action and batch limit, and the annotations cover non-destructiveness. It is still missing failure semantics for bad or already-live ids, and it dilutes itself with format notes for parameters that do not exist.

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

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

Schema description coverage is 0% for the single 'ids' parameter, so the description has to carry the load. It confirms plural entry ids and the 100-item cap (which duplicates the schema's maxItems), but never explains what an id refers to or its string format, leaving the coverage gap only partly filled.

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 ('Bring back deleted entries'), which clearly distinguishes it from write siblings like delete_transaction and update_transaction. It does not explicitly name a competing sibling (e.g. undismiss_bill/unmark_bill), 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?

No when-to-use guidance, no prerequisites, and no exclusions. It never says whether ids may mix entry types, whether already-restored ids cause errors, or when to prefer a single-item restore path.

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 (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description adds a genuinely useful behavioral fact beyond them: the operation 'adds no entries', i.e. it corrects the stored balance rather than writing ledger records. It does not mention permissions or whether the prior balance is silently replaced, keeping it out of the top band.

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 compact block of sentences, front-loaded with the core semantic ('set what an account holds now') before the formatting rules. Dense but every clause carries formatting or behavioral information; the trailing budget-period note is slightly tangential to the schema.

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 4-parameter mutation with no output schema, the description covers the semantics an agent most needs: unit convention, date format, and the no-ledger-entry behavior. Missing only edge details like auth requirements and explicit overwrite behavior.

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 0%, so the description carries the burden and largely does: it specifies that amounts are integers in minor units with a worked example (45000 = 450.00) and that dates are YYYY-MM-DD. accountId and currency are left implicit but are self-evident from the schema patterns.

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 what an account holds in one currency now) and explicitly contrasts with the ledger-writing siblings by noting it 'adds no entries'. An agent can distinguish this from add_transaction 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?

Frames the tool as 'a correction, like the app's Set balance', which gives clear context for when to reach for it versus recording a transaction. It stops short of naming explicit alternatives or when-not conditions, so it is clear context without full 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 idempotency and non-destructiveness, and the description adds real value beyond them: that amount 0 deletes the plan, that amounts are integers in minor units with a worked example, and the time-zone convention. It does not state error or permission behavior, but this is solid added context.

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

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

Front-loaded with the core action and compact. The mention of 'Dates are YYYY-MM-DD' is slightly extraneous since no date parameter exists (only a YYYY-MM period), costing a little precision.

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 write tool with no output schema and no annotation detail, the description covers the mutation's effect, value scaling, and period format adequately. Missing only edge-case/error behavior, which is minor here.

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

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

With 0% schema description coverage the description must carry the load, and it does for two of three params: amount units/scale (45000 = 450.00) and the period format/semantics (YYYY-MM budget period). categoryId is left to inference, but its name is self-evident.

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: 'Set a category's planned amount for a budget month.' This clearly distinguishes it from read siblings like get_budget and mutation siblings like copy_budget, though it never names a sibling explicitly.

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

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

'amount 0 removes the plan' hints at the two modes of use (planning vs. clearing), but there is no explicit when-to-use guidance or routing to an alternative such as copy_budget for bulk planning. Usage is only implied.

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

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

Annotations only say it is a non-destructive, idempotent mutation; the description adds the behavior an agent actually needs: the parent entry retains the remainder and the bank link so sync won't undo the split, existing parts are replaced, and an empty list reverses the split. That is substantive context beyond the structured 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 core split semantics are front-loaded, but the text repeats itself ('Amounts in minor units' stated twice) and appends date/budget-period formatting rules (YYYY-MM-DD, YYYY-MM) that do not correspond to any parameter in this tool's schema, making the entry longer than its payload justifies.

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 three-parameter mutation the replacement/reversal behavior is covered thoroughly, but two of the three parameters (`id`, `categoryId`) are left semantically undefined, and there is no output schema to fall back on for what the call returns. Adequate, not 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 0%, so the description must carry the load. It explains amount format well ('minor units (kopecks, cents): 45000 = 450.00') and part structure, but never explains the top-level `id` or the top-level `categoryId` parameter, and the 'splitOf' reference points at a field that does not exist in this schema, which risks confusion.

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?

Names a specific verb (split) and resource (expense/income entry into categorized parts) and illustrates it concretely: '1000 = 700 groceries + 300 pets'. This clearly separates it from add_transaction, update_transaction, and bulk_update_transactions, which would otherwise be the ambiguous neighbors.

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 concrete operating rules: 'The parts replace earlier ones; an empty list joins them back' and 'split the entry, not one of its parts (splitOf)'. These tell the agent how to invoke it correctly, though it never explicitly names an alternative tool or a when-not-to-use condition.

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 safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add context. It adds the reversal semantics but says nothing about failure modes (e.g., undismissing a bill that was never dismissed) or what state is restored.

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?

Only the first sentence is relevant; the amount-formatting and date-formatting sentences are boilerplate copied from other tools and earn no place in a one-string-parameter tool. The useful content is front-loaded, but most of the text is noise.

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

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

With no output schema and no annotations covering inputs, the description should explain what 'key' is and what success/failure means. It leaves the parameter undefined while documenting irrelevant formatting rules, so an agent lacks what it needs to call the tool confidently.

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 single parameter 'key' has 0% schema coverage and the description never explains it. Instead, the description spends two sentences on amount units and date/month formats that correspond to parameters this tool does not have, so it fails to compensate for the coverage gap.

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 action (undo the dismissal of a bill) and explicitly cites the sibling it reverses, dismiss_bill, so an agent can tell it apart from unrelated tools. It is slightly weakened by never saying what 'key' identifies (a bill key from list_bills), which the agent must infer.

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?

Naming dismiss_bill implies the usage context (a bill that was wrongly dismissed), but there are no explicit when/when-not rules and no differentiation from the adjacent siblings unmark_bill and mark_bill, which sound similar and are not addressed.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds no behavioral context of its own (what happens if the key is unknown or already unmarked), and instead spends its text on amount/date formatting that this tool never uses.

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 action is correctly front-loaded in the first clause, but the remaining two clauses explain minor-unit amounts and YYYY-MM-DD/YYYY-MM date conventions — none of which exist as parameters on this tool. That is inherited boilerplate that consumes most of the description without earning 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 one-parameter, annotation-covered, output-schema-less tool the definition is close to sufficient, but it omits any statement of behavior on an invalid or stale key and pads with irrelevant formatting rules instead of the missing behavioral 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?

The single `key` parameter has 0% schema description coverage, so the description must carry it. '(its key)' usefully tells the agent the value is the key returned by mark_bill, but it gives no format, length, or tolerance details, leaving the required input only partially explained.

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?

Names a specific verb (Remove) and the exact state being undone (a mark made with mark_bill), tying itself to its inverse sibling rather than restating the tool name. An agent can distinguish it from dismiss_bill/undismiss_bill/delete_transaction without opening any 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?

Usage is only implied through the inverse relationship: you call this to undo mark_bill. There is no explicit statement of when this is appropriate versus undismiss_bill or delete_transaction, and no when-not or error-condition 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 establish the safety profile (not read-only, not destructive, idempotent), and the description adds real value on top: it discloses that archiving is the only removal mechanism and that deletion never happens through this tool. It stops short of naming permissions, side effects on linked transactions, or what a successful update returns.

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 operative sentence is front-loaded and efficient, but two of the four sentences are devoted to integer-minor-unit and date-format conventions that are irrelevant to a schema containing no amount or date fields. Those sentences do not earn their place for this tool.

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 mutation tool with 11 parameters, 0% schema coverage and no output schema, the description gives the semantic essentials plus the archive semantics that annotations alone would not convey. It is slightly short of complete because three boolean/ordering parameters are left entirely unexplained.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does cover name, kind, currencies, owner, icon/color ('look') and archived. However it ignores sort, inBalance and showOnMain, and its amount/date formatting sentences describe concepts (minor units, budget periods) that have no corresponding parameters in this 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 ('Rename an account, change its kind, currencies, owner or look, or archive it') and enumerates the mutable facets. It also carves out scope by declaring accounts are never deleted here, which separates it from a hypothetical delete tool and from create_account in the sibling list.

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 archive-vs-delete distinction ('archive it (archived: true). Accounts are never deleted from here.') gives useful implied guidance, but there is no explicit when-to-use-this vs. an alternative sibling, no prerequisites, and no statement about ordering relative to other account operations.

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 safety profile (destructiveHint=false, idempotentHint=true), and 'Categories are never deleted from here' is consistent with that, adding a little clarity about non-destructive archiving. Beyond that it discloses nothing new such as what happens to a category's transactions when archived, whether archived categories remain visible, or any permission requirements.

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 leading sentence is well front-loaded and earns its place, but the two trailing sentences about integer minor units and YYYY-MM-DD/YYYY-MM date formats describe conventions for tools that take amount or date parameters — this tool has none, so that text is dead weight for the agent calling update_category.

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 six-parameter mutation with no output schema, the essentials are roughly covered and annotations handle safety, but the description omits the id/sort semantics and the consequences of archiving a category, while spending its tail on amount/date conventions that do not apply here.

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

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

With 0% schema description coverage, the description must carry parameter meaning. It covers name, icon, color, and archived (including the archived: true syntax), but never explains the required id or the sort field, leaving two of six parameters undocumented anywhere.

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 precise verb-plus-resource with the exact editable fields: rename, change icon or color, or archive. It also explicitly bounds the tool's scope ('Categories are never deleted from here'), which cleanly separates it from create_category and any delete-style sibling.

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

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

The description implies usage clearly: mutations are limited to rename/icon/color/archive, and deletion is not available here, so the archive flag is the intended alternative to deleting. It stops short of explicitly naming an alternative tool or stating prerequisites, so it does not reach full when/when-not coverage.

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, and idempotentHint=true, so the safety profile is covered. The description adds real behavioral context by explaining the done toggle (true stays done when money is spent, false reopens), which annotations cannot convey. It does not, however, state that this is a partial update (unlisted fields are left alone), what archiving actually does to the goal, or any permission requirements.

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?

It is front-loaded with the mutation list and every clause earns its place, with no filler. The first sentence is a run-on with nested parentheticals that is harder to scan than a per-field list would be, but the density is justified by the number of undocumented 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?

For an 11-parameter mutation tool with no output schema and zero schema-level documentation, the description covers amounts, dates, and most fields — enough for correct invocation. The remaining gaps (id, icon, color, archiving side effects, partial-update semantics) are real but secondary, and no return-value documentation is required since there is no output schema.

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

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

With 0% schema description coverage across 11 parameters, the description carries the full burden and mostly succeeds: it defines units (minor units, 45000 = 450.00), date format (YYYY-MM-DD in the family time zone), month format (YYYY-MM), and the null semantics for deadline and monthly. It omits three parameters entirely — id, icon, and color (the latter carrying a 16-value enum) — so the compensation is strong but incomplete.

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 (change/update) and enumerates the exact mutation surface of the resource: rename, target, deadline, months, monthly amount, account, done, archived. This makes it unambiguous against siblings such as create_goal, delete_goal, and apply_goal_cuts, which an agent can rule out without opening any 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?

Usage is only implied: the field list tells the agent what can be changed, but there is no explicit when-to-use statement, no exclusions, and no routing to alternatives (e.g. create_goal for a new goal, reorder_goals for ordering, delete_goal for removal). The null-value rules for deadline and monthly are value semantics rather than tool-selection 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 idempotent=true, destructive=false, readOnly=false. The description adds genuine behavioral context beyond them: bank-synced entries retain the bank's account, amount and date, which is a real constraint an agent cannot derive from the schema. It stops short of stating permissions, side effects on linked data, or response 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?

Front-loaded with the core action and partial-update rule, then the format details. Three compact sentences with no filler, though the closing month/period sentence does not map to any parameter and is arguably 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?

For a 13-parameter mutation with 0% schema description coverage and no output schema, the description covers partial-update semantics and value encodings but omits the meaning of most fields, especially the transfer-related trio. It is minimally viable for correct invocation of simple fields but insufficient for the full surface.

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

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

Schema description coverage is 0% across 13 parameters, so the description carries the burden and only partially meets it. It explains amount encoding (minor units, 45000 = 450.00) and date formats, but leaves the relationships between amount/toAmount/baseAmount, the transfer fields (toAccountId, toCurrency), isRefund, and type undocumented. The 'month is a budget period YYYY-MM' sentence references a format with no corresponding schema parameter, which adds confusion rather than clarity.

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 (change) and resource (an entry's fields) and clarifies partial-update semantics with 'only those you pass'. It does not differentiate itself from the close sibling bulk_update_transactions, so an agent must still infer when to use one vs the other.

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 partial-update note ('only those you pass') and the bank-synced caveat, but there is no explicit when-to-use guidance and no mention of the alternative bulk_update_transactions or add_transaction. The agent must infer the selection rule.

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