update_goalRename a goal, mark it reached or not, star it (important), set its sphere, or add a subgoal. Send only what changes. A goal linked after other goals on the canvas can be marked reached only once the goals before it in the same period are reached.
| Name | Required | Description | Default |
|---|---|---|---|
| done | No | ||
| text | No | ||
| sphere | No | Goals sphere name or id, empty string removes it | |
| goal_id | Yes | ||
| important | No | The star, like on a task | |
| add_subgoal | No |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses two genuinely additive behaviors: that updates are partial ('send only what changes') and a dependency constraint on marking goals reached. It does not say what happens on invalid goal_id or how a removal (empty sphere) interacts with the non-destructive hint.
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?
Three tight sentences, front-loaded with the operation list and followed by the two rules that matter (partial update, dependency precondition). No filler or redundancy.
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 and a 6-parameter mutation tool, the description covers operations, update semantics, and one important business rule. It omits error/validation behavior and the effect of unsetting values, which are minor gaps rather than blockers for correct invocation.
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 33% (just sphere and important are documented inline), so the description must carry the load. It does: it maps text to rename, done to reached/not, important to the star, sphere to assignment, and add_subgoal to creating a child, giving meaning to parameters the schema leaves bare.
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 names the specific operations available (rename, mark reached/unreached, star, set sphere, add subgoal) against the 'goal' resource, so an agent knows exactly what can be mutated. It does not explicitly contrast itself with close siblings like update_subgoal or update_task beyond the resource noun, so it falls just short of full sibling differentiation.
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?
Usage is implied through the partial-update instruction 'Send only what changes' and the conditional rule about marking a goal reached when it is preceded by linked goals in the same period. There is no explicit statement of when to prefer this tool over add_goal, delete_goal, or the update_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.