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

Far beyond the annotations: it documents exactly-one-of category/account/knw_row_number, the slash sub-account syntax and the 000-equals-main-account rule, the ambiguity/unknown rejection codes (BUDGET_ACCOUNT_AMBIGUOUS with sub-accounts listed, BUDGET_ACCOUNT_UNKNOWN), that a tenant-unknown account is still accepted, the signed-amount convention with file-upload magnitudes rejected, and that an invalid category writes nothing while returning valid names. Note a mild tension with idempotentHint=false in the annotations, given the description and the entries field both describe upsert semantics.

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 most decision-relevant constraint (exactly one of three key fields) is front-loaded, and nearly every clause carries a distinct rule or error code rather than restating the schema. The cost is density: it is one long paragraph with nested parentheses, so details like the forecast rule are hard to locate on a scan.

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 write tool with no output schema, the description covers validation, rejection paths, sign conventions, and the forecast-specific requirement, which is the complex part. The only gap is success behavior — it never says what comes back when all entries are accepted (count inserted vs updated), which an agent may want before chaining calls.

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 meaning the schema cannot express: the mutual exclusion of category, account, and knw_row_number per entry, and the fact that there is no separate sub_account parameter. It also explains how account values are compared (main account actuals only, no sub-account summing), which changes how an agent should choose the value.

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

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

The first clause gives a concrete verb and resource: "Insert or update budget entries (monthly values) for a plan." That is enough to tell it apart from read-side siblings such as get_budget_vs_actual or get_periodic_summaries. It stops short of naming create-budget-plan or list_budget_plans as the source of the required plan_id, so the plan-side relationship is only implied.

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

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

It gives real when-to-use context, most notably that a forecast plan's entries must cover closed months plus forecast, and it names get_periodic_summaries (category_totals) as the way to read the closed months. It never states explicit exclusions such as "do not use this to change an existing plan's metadata — use create-budget-plan", so an agent still has to infer the boundary.

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