Budget Set Flex Rollover Settings

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

The annotations already establish the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description's 'This may create or update Monarch data' is consistent with those and adds the small context that this writes to Monarch's data store. However, it reveals nothing about overwrite semantics, the effects of repeated calls, or any required preconditions. No contradiction with the annotations.

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

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

Two sentences with no filler, and the core action is front-loaded. The second sentence earns its place by disclosing the create/update side-effect profile. The brevity is efficient, though it is partly a byproduct of under-specification that the other dimensions properly penalize.

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, three of five parameters semantically undocumented, and a money-affecting mutation, the description provides far too little. An agent is left to guess the meaning of enabled, start_month, and starting_balance solely from their names, and the description doesn't tie this tool to its read sibling budget_get_flex_rollover_settings for pre-reading current state.

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

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

Schema description coverage is only 40%, leaving enabled, start_month, and starting_balance undocumented, and the tool description compensates for none of these. It adds zero meaning beyond what the schema already provides, which falls well below the threshold where the description is expected to carry the burden for under-documented parameters.

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

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

The first sentence 'Set flex rollover settings' restates the tool name and title nearly verbatim, edging toward tautology, and never explains what flex rollover settings are or what effect enabling them has. It does distinguish itself at the surface level from the read sibling budget_get_flex_rollover_settings and from other budget_set_* mutations, but the added sentence about creating/updating Monarch data speaks to side effects, not purpose.

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

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

No guidance is given on when to invoke this tool versus any of the closely related siblings such as budget_set_budget_category_rollover, budget_set_flex_budget_amount, or the read counterpart budget_get_flex_rollover_settings. There are no conditions, prerequisites, or exclusions that would help an agent select between the many budget_set_* tools.

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