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

Annotations already declare destructive/non-idempotent/openWorld, but the description adds substantial context beyond them: actions are applied UNCONDITIONALLY with no condition evaluation, wrong ids are silently changed rather than skipped, edits are bulk-capped at 500 per call, changes cannot be undone via this server, and values are ids not names. This is exactly the extra behavioral detail annotations cannot express.

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 write-vs-preview relationship and the 'SAVE' behavior are front-loaded, and each subsequent sentence adds a distinct operational fact. It is dense and runs a bit long, but almost no sentence is redundant; minor trimming possible without loss.

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, yet the description explains the return payload (updated ids plus a 'missing' list for ids that did not exist), and covers the write semantics, limits, reversibility, and id provenance an agent needs to call this 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 coverage is 100% so the baseline is 3, but the description adds real meaning: it clarifies that action values are ids rather than names (reported as toId by the preview), that actions share create_rule's format (pointing to describe_rule_schema), and restates the 500 cap. This compensates for the enum-heavy action object being otherwise opaque.

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 ('apply rule actions to transactions and SAVE') and positions itself precisely as 'the write half of preview_rule_effects', which immediately distinguishes it from the preview sibling. An agent knows exactly what this does and how it relates to the read-only counterpart.

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?

Explicit sequencing ('preview first, then pass the transaction ids it returned'), explicit source constraint (only ids from preview_rule_effects or search_transactions, never self-assembled), and an explicit warning about unconditional application. When-to-use and when-not-to-use are both covered.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true). The description adds domain behavior not covered by annotations: income categories behave differently from spending ones, and a parent group must already exist. It does not discuss duplicate-name handling or the response, but the annotation bar is already met.

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

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

Three short sentences, front-loaded with the core action, then prerequisites, then the one parameter nuance that actually requires judgment. No filler.

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

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

For a 4-parameter mutation tool with no output schema and annotations covering the safety profile, the description covers the essential prerequisites and the non-obvious parameter. Missing only edge cases (duplicate names, validation failures) that an agent might want.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the semantic distinction for `isIncome` (only for money coming in) and by clarifying that `groupId` must reference an existing group. It does not mention `hidden`, but the schema documents it.

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

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

States a specific verb (create) and resource (budget category) plus its required parent context (inside an existing category group). This cleanly separates it from the sibling create_category_group, which the description explicitly names.

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

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

Names two concrete alternatives with the condition that selects them: obtain the group id from `list_category_groups`, or create the group first with `create_category_group`. It also gives guidance on when to set `isIncome`. No explicit when-not guidance, but the routing is clear.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds domain behavior the annotations cannot: the group starts empty, must be populated separately, and is restricted to spending groups. It does not mention duplicate-name behavior or what happens on repeat calls, which is a minor gap.

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

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

Two sentences, zero filler, and the core action is front-loaded before the workflow and constraint details. Every clause carries information the agent needs.

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 full annotation coverage and no output schema, the description supplies the essential workflow and domain constraint. It stops short of describing the created resource's identifier or duplicate handling, which an agent might want, but nothing critical is missing.

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

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

Schema description coverage is 100%, so both parameters (name, hidden) are already documented in the schema. The description adds no format, constraint, or default information beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Create an empty category group') and immediately defines its scope ('to file categories under'), which cleanly separates it from create_category, list_category_groups and update_category_group. The clarification that groups are spending groups adds precision beyond the name.

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

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

Gives the when (to file categories under), the follow-up alternative ('then fill it with create_category'), and an explicit when-not: income groups cannot be created via the API and every budget already has one. An agent knows both the workflow and the boundary 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 mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description does not need to re-state safety. It adds real value by noting the return payload and by warning that this operation is the origin of duplicate payees — a behavioral consequence beyond the annotation set.

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, and the primary action is front-loaded ahead of the duplicate-avoidance caution. Every sentence earns its place.

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

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

For a single-parameter creation tool with no output schema, the description covers the action, the return value, and the key prerequisite (dedupe check). Safety semantics are handled by annotations, so nothing material is missing.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents 'name' fully. The description adds no format, length, or normalization detail beyond what the schema provides, so baseline 3 applies.

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

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

Specific verb (create) plus resource (payee), and it states what is returned (the payee with its new id). This cleanly separates it from siblings like update_payee, merge_payees, and list_payees.

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

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

Explicitly directs the agent to call resolve_name_to_id first and explains the rationale (avoiding near-duplicate names). This is a named alternative plus the condition that selects it, which is exactly the strongest form of 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?

With annotations already declaring readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, the description adds important behavioral context: the rule applies only to future imports and edits and does not retroactively change existing transactions. It also warns that conditions use ids, not names, which is a non-obvious constraint beyond the annotations.

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

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

The description is three tightly written sentences, front-loading the core action and then layering prerequisite, parameter constraint, and scope in a logical order. Every sentence adds distinct value with no repetition or filler.

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

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

For a non-idempotent create tool with rich annotations and a fully described input schema, the description covers the key operational facts: how to learn the exact format, the id-not-name requirement for conditions, and the future-only non-retroactive scope. No output schema exists, so no return-value explanation is needed.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds useful semantic meaning by specifying that condition fields reference accounts, categories, and payees by id rather than name. It also routes the agent to describe_rule_schema for exact parameter format, which helps with the nested conditions/actions structure.

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 ('Create a rule from conditions and actions') and clarifies the scope with conditions, actions, and future applicability. It also names the required prerequisite tool, describe_rule_schema, making the purpose immediately actionable.

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 instructs the agent to call describe_rule_schema first for the exact format and clarifies that conditions must reference entities by id rather than name. However, it does not mention when to use this tool versus alternatives like update_rule or preview_rule_effects, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavior beyond that: the format is a strict union and invalid pairings are rejected, which tells the agent why this call matters. It stops short of describing the response shape in more detail, but the key behavioral trait (validation strictness) is disclosed.

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

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

Two sentences, both earning their place: the first defines the return payload, the second gives the when-to-call directive and the failure mode. Front-loaded and free of filler.

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

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

No output schema exists, but the description narrates exactly what is returned (fields, operators, operations, typing, examples), and a no-param read-only tool needs little else. An agent has everything required to call it correctly and use the result.

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

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

Zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly frames this as a no-argument introspection 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?

States a specific verb and resource ('Return the exact structure of an Actual rule') and enumerates the contents: condition fields, legal operators, action operations, value typing, and examples. Clearly distinguishable from siblings like list_rules, create_rule, and update_rule.

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

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

Explicitly instructs 'Call this BEFORE create_rule or update_rule' and gives the reason (the condition format is a strict union and invalid field/operator pairings are rejected). Names the alternative tools and the condition that selects this one.

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 the description adds context beyond them: the deliberate conservative matching policy, the fact that a false positive feeds an irreversible merge, that nothing is merged automatically, and that transfer payees are never included. This is exactly the extra behavioral context annotations cannot convey.

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?

Opens with the core grouping rule and example, then layers caveats (matching is exact, empty result meaning, no auto-merge, transfer exclusion) in order of importance. Every sentence carries distinct information; nothing is redundant.

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

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

With no output schema, the description still explains the return shape (groups with suggestedTarget, candidates, and reason) and the operational caveats an agent needs before routing to merge_payees. Nothing material is missing for a one-parameter read-only analysis tool.

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

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

Schema coverage is 100% and there is a single optional parameter, so the schema fully documents minGroupSize. The description adds no further semantics about it, which is the expected baseline when the schema does the heavy lifting.

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

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

The description states a precise verb (group) plus resource (payees) and immediately defines the exact matching criterion with concrete examples. It clearly separates itself from list_payees and merge_payees by naming both as adjacent steps in the workflow.

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

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

Explicitly says when the tool applies (name-shaped duplicates only) and when it does not ('an abbreviation and its expansion do NOT group'), warns that an empty result does not mean 'no duplicates', and directs the agent to scan list_payees and then confirm with merge_payees. Both the alternative and the exclusion condition are named.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond that: amounts are integer cents, spending is negative, carryover flag is present, and income categories behave differently (money tracked as `received`, budgeted/spent/balance zeroed). The warning never to report an income category as '0 spent' is exactly the kind of domain nuance an agent cannot infer from structure.

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

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

Front-loads the summary of returned data before the income-category caveat, and every sentence carries information. The second paragraph is dense but justified, as it prevents a real misinterpretation; only marginally longer than strictly necessary.

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 full burden of describing return values, and it does so thoroughly — totals, per-category fields, units, sign convention, and the income-category exception. Nothing an agent needs to interpret the result is missing.

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

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

Schema coverage is 100% and the single `month` parameter is fully documented in the schema as YYYY-MM. The description adds no format or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read one month's budget') and enumerates exactly what the response contains: totals, per-category budgeted/spent/balance, and the carryover flag. An agent can distinguish this from list_budget_months (enumeration) or set_budget_amount (mutation) without inspecting 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?

Explicitly frames the use case with 'This is the tool for "am I over budget?"', giving a clear scenario for selection. It does not, however, name an alternative tool or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely useful non-obvious behavior: it returns `{ note: null }` when no note exists, which an agent cannot derive from annotations or the input schema. It does not, however, describe the populated return shape or any auth scope.

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

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

Two short sentences, zero filler, with the core action stated first and the edge-case return value second. Every clause earns its place.

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

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

With no output schema, the description usefully documents the empty-return behavior, and the single 100%-covered parameter needs no further explanation. It stops short of sketching the success shape, which would have made it fully self-sufficient.

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

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

Schema coverage is 100%, so the id parameter is fully documented in the schema (pattern, minLength, description). The description only adds the parenthetical list of entity kinds, which is marginal value beyond the schema. Baseline 3 applies.

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

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

Specific verb+resource+scope: 'Read the note attached to an entity ... by its id.' It is clearly distinguishable from the write-side sibling update_note, though it never names that sibling explicitly. Purpose is unambiguous 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?

Usage is implied by 'Read the note' and the field-level id reference, and the read-vs-update split against update_note is inferable, but there is no explicit when-to-use or when-not-to-use guidance. Adequate minimum but with a clear 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 declare readOnly/idempotent/non-destructive, and the description adds behavior those annotations cannot express: the result set is uncapped, and split transactions are returned as parent + legs with `isParent`/`isChild`, so naive summing double-counts. That return-shape warning is exactly the kind of context beyond structured fields.

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

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

Two sentences, zero waste: the scope and routing rule come first, the split-accounting caveat second. Every clause earns its place.

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

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

With no output schema, the description still discloses the one return-shape detail an agent would otherwise get wrong (parent/child split rows). Combined with the exhaustive-read scoping, an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100% and the schema documents all three required parameters with formats and inclusivity; the description adds no parameter-level syntax or meaning beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (list), resource (transactions), and scope (one account, between two dates, no result cap), and explicitly contrasts itself with the sibling `search_transactions`. An agent can distinguish it from every other sibling 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 an explicit when-to-use rule ('exhaustive per-account read, e.g. for reconciling') and names the alternative plus the condition that selects it ('use search_transactions for anything cross-account or filtered'). Nothing 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?

The annotations declare idempotentHint: true, but the description explicitly states the opposite: 'calling twice with 1000 leaves 2000 held.' That is a direct contradiction of the idempotency annotation, which would mislead an agent deciding whether a retry is safe. The rich detail about clamping and the returned fields is genuinely useful, but the conflict with structured metadata forces the lowest score.

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 unit, then layered with the additive rule, the correction path, and the clamping caveat. It is a bit dense at four sentences, but every sentence carries operational information an agent needs before calling.

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 compensates by naming the response fields (`heldAmount`, `forNextMonth`, `held: false`) and explaining how to interpret a partial or empty hold. Combined with the additive semantics and correction procedure, an agent has everything needed to call and read this tool correctly.

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

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

Schema description coverage is 100%, so both `month` (YYYY-MM) and `amount` (cents) are already fully documented; the baseline is 3. The description adds real semantics beyond the schema by explaining clamping to available surplus and that the resulting hold can be smaller than requested, but it does not extend the parameter definitions themselves.

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 ('Hold ... leftover "to budget" money back for next month') with the unit of measure (integer cents) and the scope (this month's surplus). It is clearly distinguishable from siblings like set_budget_amount, set_budget_carryover, and reset_budget_hold.

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

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

Explicitly gives the correction path ('To correct a hold, call reset_budget_hold first') and clarifies that the call is additive rather than replacing, which is exactly the guidance an agent needs before invoking. It stops short of a full when/when-not comparison against set_budget_carryover or set_budget_amount, so it is strong but not exhaustive.

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

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

Goes well beyond the annotations by disclosing a side effect — 'The budget is synced with the server before reading' — which readOnlyHint/idempotentHint do not convey, and by explaining balance semantics: figures are as of TODAY, future-dated or scheduled transactions are excluded, and results may diverge from Actual's own account screen. That is exactly the kind of behavior an agent would otherwise get wrong.

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 purpose and return shape, then the freshness caveat and the agent-facing instruction. Every sentence carries information, though the enumerated field list is fairly dense and slightly redundant with itself ('amount' vs 'amountDecimal').

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 correctly takes on the job of describing the return payload (id, name, amount, amountDecimal, off-budget/closed flags, onBudgetTotal, total) and the syncing and balance-timing behavior. An agent has everything needed to call it and interpret results without surprises.

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 no parameters, so there is nothing for the description to disambiguate — the baseline of 4 applies. The prose spent on return fields is instead handled under transparency and completeness.

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

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

States a specific verb and resource ('List every account in the Actual Budget file with its current balance') and immediately scopes the return set. No sibling tool does the same thing, and the description makes clear it is the roster-and-balance reader rather than a transaction or category lister.

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 context for when to reach for it and adds an actionable instruction ('Mention that if a balance looks off rather than assuming the budget is wrong'), which is genuine usage guidance. It does not, however, name an alternative or state exclusions (e.g., that it cannot filter by account or date).

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 behavior, so safety is covered. The description adds genuinely new behavioral context not in the annotations: results are ordered oldest first and formatted as YYYY-MM, 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?

Two tight sentences with zero waste. The scope and ordering are front-loaded, and the second sentence is purely actionable 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?

With no parameters, no output schema, and full annotation coverage, the description supplies the two things an agent actually needs to know about the return value: the ordering and the date format. Nothing material is missing.

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

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

The tool takes zero parameters, so this dimension is at baseline 4 per the rules. The description correctly does not spend words on nonexistent inputs.

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

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

States a specific verb (List) and resource (every month the budget file covers), plus the ordering and output format. This clearly distinguishes it from the singular sibling get_budget_month, which the agent can tell apart without opening schemas.

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

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

Explicitly says to use it to find the current or most recent month before reading or setting budget amounts, which routes the agent to the correct downstream tools (get_budget_month, set_budget_amount). It lacks an explicit exclusion statement, but the when-to-use context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds a useful behavioral detail: hidden categories are excluded unless includeHidden is true. However, it does not describe pagination, rate limits, or other runtime behavior. With annotations covering safety, this is an adequate but not rich behavioral 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?

Three sentences, each earning its place: first states what is listed and the fields returned, second gives usage context, third states the default filtering behavior. The information is front-loaded with the core purpose, then context, then a detail. No waste.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers purpose, usage context, and the main behavioral detail. It omits discussion of return format (but no output schema exists) or edge cases like empty results, but overall it is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the parameter's meaning is already fully documented. The description adds the default behavior context ('Hidden categories are excluded unless includeHidden is true'), which reinforces and slightly clarifies the schema. It does not add syntax or format details, but the parameter is simple and well-covered by the schema.

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

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

States a specific verb+resource ('List every budget category') and specifies the returned fields (id, name, containing group). It distinguishes itself from sibling list tools like list_category_groups and list_accounts because the description makes the resource explicit.

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?

Clearly states the context in which this tool should be called first: 'Categories are addressed by id by the budgeting and rule tools, so this is usually the first call when working with either.' This provides strong usage guidance by naming downstream tools that depend on the result. It does not provide explicit exclusions, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds behavioral value by disclosing that hidden/empty groups behave differently from list_categories and that categoryCount: 0 is a meaningful signal. It does not, however, note the includeHidden default or ordering/pagination behavior, so it stops short of full disclosure.

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

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

Two sentences, zero filler. The core purpose is front-loaded and the routing advice to create_category/list_categories follows immediately, with the most decision-relevant detail (empty group discoverability) placed last for emphasis.

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 carries the burden of describing the return shape — and it does (ids plus per-group category counts). Combined with the sibling routing and the annotation-covered safety profile, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100% and the single parameter (includeHidden) is fully documented in the schema, so baseline 3 applies. The description adds no syntax or semantics for that parameter — the only parameter-adjacent hint is the categoryCount: 0 example, which is about output rather than input.

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

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

States a specific verb (List) and resource (category groups) and specifies the returned content: group ids and category counts. It also explicitly contrasts with the sibling list_categories, so an agent can differentiate them 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?

Gives an explicit when-to-use ('Use this to find the groupId for create_category') and names the alternative plus the exact condition that makes this tool necessary — empty or new groups (categoryCount: 0) are only discoverable here. No inference required.

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 safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real behavioral context: the default-withUsage enrichment, which fields appear, and the domain rule that transferAccountId payees are transfer counterparts that must not be merged. It omits volume/pagination behavior for a potentially large enumeration.

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

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

Three sentences, front-loaded with the core action, then the enrichment payload, then the safety constraint. Every sentence carries information; none is filler.

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

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

With no output schema, the description responsibly explains the returned fields and the default behavior, and annotations cover safety. It is nearly complete for a simple list tool, lacking only scale/pagination notes and whether results span all accounts.

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

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

Schema coverage is 100% and the schema already documents withUsage's meaning, default, and the speed tradeoff. The description goes beyond it by explaining why the enriched fields matter (enabling cleanup/merge decisions), giving the parameter semantic weight rather than just repeating the schema.

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

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

States a specific verb and resource ("List every payee") and immediately details what the returned set contains, so an agent knows this is the enumeration tool rather than a lookup or mutation tool. It is easily distinguished from siblings like create_payee, update_payee, and merge_payees.

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 context for use (cleanup/merge decisions, picking the busiest payee as merge target) and an explicit exclusion (payees with transferAccountId must never be merged). It stops short of naming sibling tools such as find_duplicate_payees or merge_payees as the follow-on alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real context beyond them: it discloses that each rule carries conditions and actions, and that payeeId narrows to rules the system 'associates' with a payee (an implicit association the agent could not infer from the schema).

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

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

Two sentences, no filler, and the core action is front-loaded before the optional-filter guidance. Every clause carries information.

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

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

A single optional-param, read-only list tool with a fully documented schema and an annotation-covered safety profile. The description covers purpose, filter semantics, and the rough return content (conditions plus actions), which is sufficient with no output schema present.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by explaining what the payeeId filter is actually for (debugging why a merchant's transactions consistently get a category), adding intent the terse schema description does not.

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 ('List the budget's rules') and even describes the shape of what is returned ('with their conditions and actions'). It is clearly distinct from create_rule/update_rule/apply_rule_actions, though it does not explicitly name the lookalike siblings (describe_rule_schema, preview_rule_effects).

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 usage context for the optional parameter: pass payeeId to see why transactions for one merchant keep getting a category. It stops short of stating when to prefer this over preview_rule_effects or describe_rule_schema, so no explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safe read-only nature is known. The description adds the diagnostic context that scheduled transactions can affect budgets/rules, but doesn't disclose return format, pagination, or authentication requirements. With annotations covering the safety profile, a 3 is appropriate.

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

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

Two sentences, front-loaded with the core action and followed by useful context. No wasted words, though the second sentence could be slightly tighter.

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

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

Given zero parameters, rich annotations, and no output schema, the description gives a basic explanation of what the tool returns and one use case. However, without an output schema, the description could clarify whether it returns a simple list or detailed recurring schedules, and how it relates to other list tools. It is adequate but not comprehensive.

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

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

The tool takes zero parameters, so baseline is 4. The description provides no param information and doesn't need to, as there is nothing to document.

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

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

Clear verb+resource: 'List Actual's scheduled (recurring) transactions', with clarifying synonyms and mention of key return fields (next due date, amount). It doesn't explicitly contrast with sibling tools like list_rules or get_budget_month, so it lacks full sibling differentiation, 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?

Provides a hint of when it's useful ('useful context when a budget or rule looks wrong'), which implies a diagnostic use case, but does not state when to use it versus alternatives or when not to use it. No alternative tools are named.

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 and destructiveHint=false, so safety behavior is covered structurally. The description adds the semantic link to rule tag-matching, which is genuinely useful context, but says nothing about return format 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?

Two short sentences, both earning their place: the first defines the resource, the second explains its relevance. No filler and the core purpose is front-loaded.

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

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

For a trivial, annotation-covered, parameterless read tool with no output schema, the description supplies the domain context needed to know why tags exist. Only return-value shape is unaddressed, which is acceptable 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering arguments are needed, and the schema has nothing further to document.

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

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

States a specific verb (List) and resource (tags) with the scope 'defined in this budget'. It is clearly distinguishable from the many sibling list_* tools by resource, though it does not explicitly name or contrast them.

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 context for when this matters: the tags are 'the vocabulary available' to rules using `hasTags` in transaction notes. That frames a real use case (rule authoring), but there is no explicit when-not guidance or pointer to an alternative.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the irrevocability is partially covered. The description still adds specifics annotations cannot: that it voids transfers when target has a transferAccountId and that merged payees are removed. That is real added context beyond annotations, but it repeats the irreversibility the annotation already encodes, so a 3 is fitting.

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 irreversible warning is front-loaded before the operational details, and three sentences each carry distinct content. Slightly dense in the middle, but no filler sentences.

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, open-world operation with no output schema, the description covers preconditions, in-place effects, and failure modes. It does not describe the return value, but there is no output schema to lean on and the tool's effects are the important information 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?

Schema coverage is 100%, so baseline is 3. The description adds the non-obvious distinction that ids are taken, not names, which is a semantic constraint beyond the schema, and clarifies that mergeIds cease to exist and targetId is retained. Slightly above baseline.

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

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

States a specific verb (merge) and resource (payees), plus the exact transactional semantics: transactions move to target and merged payees are removed. Distinguishable from sibling find_duplicate_payees (which finds, not merges) and create_payee/update_payee.

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

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

Explicit when-to-use (only when payees really are the same merchant), a hard precondition (never merge a payee with a transferAccountId), and a failure mode to avoid (near-miss names). Nothing is left to inference for an irreversible operation.

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=true, destructive=false, idempotent=true. The description goes well beyond: it discloses that Actual only applies rules on import/edit so existing transactions are untouched (the key behavioral subtlety), that rules interact by rank so attribution is ambiguous, that unchanged transactions are omitted (empty entries + non-zero scanned = no-op), and that it reports net effect of the whole ruleset. This is rich, non-obvious behavioral context that annotations cannot convey.

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 the no-save guarantee; then flow, then the critical caveat (whole-ruleset, rank interaction), then output-shape guidance. Each sentence earns its place with distinct, actionable information. No filler.

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

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

For a 10-param read-only tool with no output schema, the description compensates by explaining the shape of the response (from/to, fromId/toId), the empty-entries case, and the interop handoff to apply_rule_actions. Annotations cover safety; description covers behavior and output interpretation. Everything an agent needs to call and interpret this correctly is present.

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

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

Schema coverage is 100%, so all 10 filter parameters are documented in the schema (limit, dateFrom/dateTo, payeeId, accountId, categoryId, notesContains, uncategorized, payeeNameContains, offset). The description adds semantic value by explaining what the response contains ('from'/'to' names plus 'fromId'/'toId') and instructing the caller to 'pass toId as the action value to apply_rule_actions' — a non-obvious interoperability hint. The description doesn't cover pagination semantics, but the schema does note 'Keep the other filters identical.' Solidly above baseline.

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

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

States a specific verb and resource ('Run the budget's rules over EXISTING transactions without saving anything, and report the field changes they would make'). This clearly distinguishes it from apply_rule_actions (which saves) and create_rule (which authors). The distinction between preview and apply is explicit and unambiguous.

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

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

Explicitly names the flow: 'create_rule, then this to check it against real data, then apply_rule_actions to make the changes stick.' It also gives an important caveat: this is a net effect of the ENTIRE ruleset, not one rule, and it points the agent to list_rules to disambiguate. This is textbook when-to-use/when-not guidance with named alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered; the description still adds value by spelling out the mutation effect (hold is moved back to this month's 'to budget') and the no-op-when-empty behavior. It stops short of noting irreversibility or permission needs.

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, effect stated first, safety condition second, return value last. Every sentence earns its place with no padding.

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

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

With only one well-documented parameter, no output schema, and annotations carrying the safety hints, the description fills the remaining gap by naming the returned `forNextMonth` value and its expected 0 result. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single `month` parameter is fully documented in the schema (format YYYY-MM). The description adds no syntax or format detail beyond that, so baseline 3 applies.

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

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

States a specific verb ('Release') and resource ('everything held back for next month'), plus the effect (returns it to this month's 'to budget'). The inverse relationship to hold_for_next_month is clear from semantics, though the sibling is never named, which keeps it just 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?

'Safe to call when nothing is held' gives one call condition (no-op safety), which is genuine guidance. It never states when to prefer this over hold_for_next_month or other budget tools, so usage is only implied rather than routed.

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 read-only/idempotent/safe, but the description adds a genuinely non-obvious behavior: a miss returns `{ id: null }` rather than an error. That return semantics disclosure is exactly the kind of context annotations cannot carry and directly prevents an agent from treating a null result as a failure.

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

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

Three short sentences, front-loaded with the action, then the null-result caveat, then the rationale. Every sentence earns its place and none repeats structured data unnecessarily.

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, yet the description supplies the essential return contract (id or null) and the error-vs-normal distinction. With only two fully documented params and full annotation coverage, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, with both `name` (exact name to match) and `type` (enum of entity kinds) fully documented in the schema itself. The description's mention of 'exact name' and the entity list only restates the schema, so baseline 3 applies.

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

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

States a specific verb (look up) and resource (the id of an account, category, payee, or schedule), enumerating the entity kinds the `type` enum accepts. It is clearly distinguishable from siblings like list_accounts or list_payees, which enumerate rather than resolve a single name.

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

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

Explicitly frames the when: use it to check whether something exists before creating it, and notes the alternative it replaces — listing everything just to find one id. The condition selecting this tool over the list_* siblings is stated, not inferred.

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 mark it destructive and non-idempotent; the description adds crucial context beyond them – it's slow and rate-limited by the bank, fails rather than hollow-succeeding, and returns accounts synced, not transaction counts. It also warns follow-up is needed for counts, which is behavior annotations cannot convey.

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 tight sentences, front-loaded with the action and common case, then rate-limit warning, then failure/return behavior. No filler and every clause adds actionable context.

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

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

Covers prerequisites (bank link required), side effects (slow, rate-limited), failure modes, and return semantics (accounts synced, not counts), plus a routing hint. Complete for a mutation tool with no output schema.

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

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

Schema coverage is 100% and the accountId description already states 'Sync only this account. Omit to sync every linked account.' The description repeats that semantics without adding format or edge-case detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (trigger bank sync) and resource (linked bank accounts / transactions), and adds scope detail ('optionally for one account'). Distinguishes from sibling sync_budget and from read tools like search_transactions by name.

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

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

Explicitly says when to call it deliberately vs. alternatives: 'call it deliberately rather than before every read,' and directs to search_transactions for counts. Failure conditions (account does not exist, closed, no bank link) give clear 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 cover read-only, idempotent, non-destructive, open-world behavior, so the description's job is to add beyond that. It does: newest-first ordering, the limit cap (default 100, max 1000), and what `truncated` means. It stops short of describing rate limits or search-cost characteristics, hence a 4 rather than 5.

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 dense sentences, front-loaded with filter scope, then semantics, then result/paging behavior, closing with the sibling differentiation. Every sentence adds operational information; nothing is filler.

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

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

With 14 optional parameters and no output schema, the description carries ordering, truncation, paging, and unit conventions — exactly the gaps the schema cannot cover. All optional params are documented in the schema, and the description covers the behavior an agent needs to page and interpret results correctly.

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

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

Schema description coverage is 100%, so the 3 baseline is met by the schema alone; the description adds genuine meaning on top, notably that amounts are integer cents and negative signifies an outflow. It also clarifies the limit/offset interaction. It does not explain the cleared vs reconciled distinction, which is the one remaining param-level ambiguity.

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 (search) and resource (transactions) plus the full scope of filterable dimensions, and explicitly contrasts itself with the per-account listing sibling: it answers "where else does this payee appear?" which the per-account tool cannot. An agent can distinguish it from get_transactions 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?

Names a concrete use case (payee cleanup) and the alternative it displaces (per-account listing), and gives an explicit paging rule: use `offset` or narrow filters when `truncated` is true rather than assuming full coverage. When-to-use and how-to-continue are both spelled out.

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 safety profile (destructive, idempotent, openWorld, non-readOnly). The description adds genuinely useful behavior beyond that: the value replaces rather than increments the existing amount, and the resulting budgeted/spent/balance figures are returned so the effect is immediately visible.

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 tight sentences, front-loaded with the core action and scope, then the replace semantics, then the return behavior. No filler, and each sentence earns its place.

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

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

With no output schema, the description helpfully discloses the returned budgeted/spent/balance figures, and the replace semantics are covered. It is essentially complete for a 3-param mutation, though it does not mention auth/permission requirements for modifying a 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 100%, so month format, cents, and categoryId sourcing are already documented in the schema. The description restates cents and the replace semantics but adds no syntax or format detail beyond the structured fields; baseline 3 applies.

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

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

States a specific verb (set) plus the resource and precise scope (one category, one month, integer cents). This clearly separates it from sibling mutation tools like set_budget_carryover, hold_for_next_month, and sync_budget.

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 operation but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as sync_budget or hold_for_next_month. An agent must infer that this is the direct single-category override 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?

With annotations already declaring destructiveHint=true and idempotentHint=true, the description adds high-value behavioral context beyond them: the flag applies from the given month FORWARD to the end of the budget range, overwriting later months including deliberate ones, and the result reports only the named month. This is exactly the sort of scope/overwrite disclosure that prevents misuse.

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

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

The description is front-loaded with the core action, then adds the critical scoping caveat in a clearly marked IMPORTANT section. Every sentence earns its place, and there is no redundancy.

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

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

For a destructive, forward-applying tool with no output schema, the description covers the action, the multi-month consequence, overwrite behavior, and what the result reports. An agent has enough to call it correctly and to communicate the change accurately.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes beyond the schema by explaining the meaning of the carryover boolean (unspent rolls forward vs. overspend carries negatively) and by clarifying that the month parameter is not a one-month scope but a starting point. It adds real semantic value beyond the field descriptions.

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

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

The description states a specific verb and resource: toggling rollover/carryover for a category, with a clear explanation of what carryover means ('unspent balance rolls into the next month'). It distinguishes the effect from 'returning to to budget,' but does not explicitly contrast with siblings like hold_for_next_month or set_budget_amount.

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 effect described (unspent balance rolls forward, overspend carries as negative), and the IMPORTANT note gives a critical when-to-be-careful context about applying forward. However, it does not name alternatives or state explicit when-not-to-use conditions relative to sibling tools.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful context: that most reads auto-sync and this is only needed to force refresh of external UI edits. It doesn't cover failure/offline behavior or rate limits, keeping it short of a 5.

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

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

Two tight sentences, front-loaded with the action and followed by the decision rule. No filler.

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

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

With no parameters and no output schema, the description only needs to convey purpose and timing, which it does. Minor gaps remain around what happens if the sync fails or if edits conflict, but nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. Schema coverage is 100% and nothing is left ambiguous.

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: 'Pull the latest changes from the Actual sync server.' This distinguishes it from the similarly named sibling run_bank_sync, which targets a different sync source.

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 both the trigger ('after editing the budget in the Actual UI and wanting those edits reflected immediately') and an implicit exclusion ('read tools already sync where it matters'), so the agent knows when this tool is unnecessary.

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 destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description complements these by clarifying partial-update behavior and positioning hiding as the non-destructive path that preserves history, which is genuinely useful context beyond the annotations. It does not contradict the destructive hint.

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

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

Three short sentences, front-loaded with the operations, followed by the update semantics and the safety rationale. Every sentence earns its place with no redundancy.

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

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

For a 4-param mutation tool with no output schema, the description covers operations, partial-update behavior, and the hide-vs-delete tradeoff. It is nearly complete; only error/permission behavior is left unaddressed, which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: partial updates via 'only the fields you pass are changed' and the historical-preservation consequence of setting hidden. That clarifies the patch-style contract the schema alone does not state.

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 ('Rename', 'move', 'hide/unhide') and resource ('a category'), enumerating the three supported mutations. This clearly distinguishes it from siblings like create_category, update_category_group, and 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?

'Only the fields you pass are changed' establishes patch semantics, and 'Hiding... is the safe alternative to deleting a category you no longer use' gives an explicit when-to-use recommendation. It lacks a named alternative tool for the delete case, but the guidance is concrete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds genuinely non-obvious behavior: hiding a group cascades to every category inside it and surfaces in list_categories as hidden. It also clarifies PATCH-style partial-update semantics. It omits any auth/permission notes, keeping it just short of 5.

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 tight sentences, front-loaded with the two supported operations, then update semantics, then the cascade warning. No filler or repetition.

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

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

A three-parameter mutation tool with no output schema and full annotation coverage: the description covers operations, partial-update behavior, cascade side effects, and the correct recovery path. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the downstream consequence of the `hidden` parameter (all child categories reported hidden, and the group is the correct place to reverse it) and by restating partial-update semantics.

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 ('Rename a category group or hide/unhide it') and immediately scopes what changes ('Only the fields you pass are changed'). It is clearly distinguishable from sibling tools like update_category and create_category_group.

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 guidance for the hide/unhide case and names the alternative behavior ('unhide the group here rather than trying to unhide them one by one'). It doesn't state when to prefer this over update_category, but the resource boundary is unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond them by explaining that notes 'overwrite wholesale,' clarifying exactly what gets destroyed, plus a read-before-append workflow hint.

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

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

Two tight sentences with no filler; the replacement semantics are front-loaded before the append alternative. Every clause earns its place.

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

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

For a 2-param mutation tool with rich annotations and no output schema, the description covers the key behavioral facts an agent needs (wholesale replacement, read-first workflow). Nothing critical is missing, though idempotency is only implied via annotations rather than stated.

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

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

Schema description coverage is 100%, so both `id` and `note` are already documented in the schema. The description only restates 'by its id' and 'free text,' adding no syntax or format detail beyond structured fields; baseline 3 applies.

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

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

States a specific verb (Replace) and resource (the note attached to an entity by its id), making the operation unambiguous. It is clearly distinguishable from sibling get_note, which reads rather than overwrites.

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

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

Explicitly routes the agent: read the existing note first with `get_note` if the intent is to append, which is a concrete when-to-use alternative. It stops short of stating when not to use this tool, so it falls just below the top score.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is carried structurally. The description adds real non-obvious context on top: renaming is the sole exposed payee edit, it does not merge records, and other payee attributes are unreachable — useful scope disclosure that the annotations cannot express. It stops short of stating auth/permission requirements or what happens on an id that does not exist.

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, all front-loaded: what it does, then the scope limitation, then the routing to the sibling tool. No sentence is filler and none restates the title verbatim without adding information.

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

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

With annotations covering safety/idempotency and a fully described two-parameter schema, the description supplies the remaining decision-relevant facts (non-merging behavior, sibling routing, unreachable fields). No output schema exists, so return values need not be explained, but a brief note on duplicate-name or missing-id behavior would close the last gap.

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

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

Schema description coverage is 100% with only two parameters, both documented ('Id of the payee to rename.', 'The new name.'), so the baseline is 3. The description adds no naming-format, uniqueness, or collision semantics beyond what the schema already states.

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 ('Rename a payee') and immediately scopes it against siblings: it is the only edit the public API exposes for payees, and it does not merge. An agent can distinguish it from create_payee, merge_payees, and list_payees 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?

Explicitly names the alternative for the adjacent use case ('to combine two payees, use `merge_payees`') and states an exclusion (favorite/category-learning flags are not reachable here). This is exactly the when/when-not/alternative guidance the dimension asks for.

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 and idempotentHint, but the description adds the operationally critical detail the annotations cannot convey: this is a full overwrite, so anything omitted is dropped rather than preserved. That is exactly the kind of consequence an agent must know before invoking a destructive write.

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

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

Three short sentences, zero filler, and the destructive overwrite warning is front-loaded ahead of the read-first advice. Every sentence earns its place.

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

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

With five parameters fully documented in the schema and annotations covering safety and idempotency, the description supplies the one missing piece — full-replacement semantics and the recommended read-before-write step. Nothing needed to call this correctly is absent.

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

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

Schema description coverage is 100% and the schema itself already states conditions and actions are 'the complete ... set, not a partial update.' The description reinforces the same point but adds no syntax, format, or meaning beyond the structured fields, so the baseline 3 applies.

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

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

States a precise verb+resource ('Replace a rule's conditions and actions') and the replace semantics immediately distinguish it from create_rule and from a hypothetical partial-update tool. An agent can tell what it does 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?

Explicitly names the prerequisite workflow — read the current rule with `list_rules` first — and the condition that makes that necessary (omitted data is dropped). It does not say when NOT to use this tool (e.g. use create_rule for new rules), so it falls just short of a full when/when-not/alternative statement.

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 the mutation safety profile (destructive, idempotent, open-world), so the bar is lower, yet the description adds genuinely non-obvious behavior: partial-update semantics ('only the fields you pass are touched'), null-as-clear, and that server-side rules may rewrite a value on write so the response must be trusted over the request. That last point is exactly the kind of trait annotations cannot express.

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

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

Four short sentences, front-loaded with the mutable field list, then the partial-update rule, the unit convention, and the return/rewrite caveat. Nothing is redundant and each sentence carries distinct information.

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

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

No output schema exists, but the description compensates by explaining the return value ('returns the transaction as stored afterwards') and warning that rules may rewrite values, which is the key thing an agent needs before trusting its own input. Combined with annotations covering destructiveness and idempotency, nothing material is missing for a 7-parameter mutation tool.

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

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

Schema description coverage is 100%, so each parameter is already documented, including null-to-clear and cents semantics. The description reinforces the null-clearing rule across category, payee, and note and restates 'Amounts are integer cents,' but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb (Change) and resource (a transaction) and enumerates exactly which fields are mutable (category, payee, notes, cleared flag, date, amount). It also positions itself against siblings by declaring 'The main tool for recategorizing during cleanup,' which lets an agent distinguish it from rule-authoring or note tools.

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

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

Gives clear usage context ('the main tool for recategorizing during cleanup') and an operational rule for clearing values via null. It does not, however, name an explicit alternative or state when NOT to use it (e.g. use update_note for bulk note edits, or apply_rule_actions to recategorize many transactions).

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