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

Annotations already declare non-read-only, non-destructive, closed-world, so safety is covered. The description adds material context beyond them: the $0.10 per-call cost, the API-key requirement, and an anti-fabrication behavioral constraint that shapes how the agent must gather input. Return-shape disclosure is unnecessary given an output schema exists.

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 purpose, then exclusions, then field conditions, then the behavioral rule and cost. Nothing is redundant or 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?

The description captures the decision-critical conditional logic and the guardrail against invented goals, and the output schema relieves it of explaining returns. However, for a 17-parameter tool with near-zero schema description coverage, the many optional lifecycle fields (target_type default, dates, current_value, motivation/obstacles) remain opaque to an agent.

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 only 12% (17 params, essentially only request_id/idempotency_key documented), so the description carries the burden. It does add the highest-value information — conditional field requirements for numeric (target_value, target_unit) versus habit (habit_frequency, habit_target_count) goals — but leaves category, priority, obstacles, motivation, target_type, dates, current_value, and checkin_frequency entirely unexplained.

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 life goal") and immediately scopes it ("the user explicitly wants to track"). Explicitly excludes adjacent concepts ("Not a calendar event or streak tracker"), which is exactly the differentiation an agent needs against log_event/get_trackers/create_condition siblings.

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 a clear positive trigger (explicitly-requested life goal) and a negative one (not a calendar event or streak tracker), plus an operational rule: "Ask for missing facts; never invent aspirations." It stops short of naming the concrete sibling tools (get_goals, update_goal, create_condition) an agent should consider instead, which keeps it at 4 rather than 5.

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