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

Beyond the annotations (non-read-only, destructive hint), it discloses the critical pending-proposal semantics: the tool only creates a pending proposal and nothing is recorded until confirm_proposal is called. It also clarifies that name and currency are preserved on update, removing ambiguity about how existing budgets behave.

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?

Each sentence earns its place: purpose, field selection by mode, return value, required follow-up, and the pending-proposal warning. The structure is front-loaded and compact with 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?

Given six parameters, no output schema, and partial annotations, this is complete enough for correct invocation: the agent knows what to pass, what it returns, and what to do next. The only minor omission is categoryId, but the create path is explicitly specified without it.

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

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

With 67% schema coverage, the description adds important conditional parameter semantics: create requires name, allocated, and currency, while update keeps name/currency from the existing budget. However, categoryId is never explained in either the description or the schema, so a small semantic gap remains.

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

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

The description opens with a specific verb and resource: 'Propose creating a new budget or updating an existing one's amount.' It clearly differentiates create from update and is readily distinguishable from sibling proposal tools such as propose_delete_budget and confirm_proposal.

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 explicit field requirements per mode ('For create: provide name, allocated, currency. For update: provide envelopeId, allocated'), tells the agent to call confirm_proposal with the returned proposalId after approval, and notes there is no UI button/card in this context. It also instructs when to pass editsProposalId and how to look up pending proposals with listPendingProposals.

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