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

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

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

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

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

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

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

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

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

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

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

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

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

States a specific verb and resource ('Create a goal on an account') and then enumerates the three distinct kinds (save, emergency, debt) with their distinct semantics. This clearly separates it from siblings such as update_goal, list_goals and delete_goal.

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

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

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

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