Change a Flow's plan before launch

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

Goes well beyond the annotations: it discloses that the update is whole-plan replacement ('a part left out or set to null is dropped'), that the server re-validates and refuses a keyword or page address already in use, and that the response carries the new plan plus a new planHash to show the person. It also clarifies 'Nothing is created or sent', narrowing what destructiveHint actually means. The only unstated trait is what a refusal/validation failure looks like to the caller.

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?

Purpose is front-loaded and every sentence carries information (replacement semantics, validation, response shape, precondition). It is a dense single paragraph of chained colon/semicolon clauses, though, which makes it slower to scan than it needs to be for a tool an agent will call repeatedly.

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 deeply nested two-parameter mutation with no output schema, the description covers what an agent needs: the read-modify-write loop through get_goal, the drop-on-omission rule, the uniqueness refusal, and the return value. Nothing critical is left for the agent to infer.

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 schema already documents goalId and the entire nested plan, and the baseline is 3. The description does add genuinely useful semantics the schema cannot express: the plan must be sent whole as postfjord_get_goal returned it, and omitted or null children are dropped rather than preserved. That is real added meaning, but it is not parameter-by-parameter guidance, so it sits above baseline rather than at the top.

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 (changes the plan of a proposed goal) and then enumerates the concrete edits it covers: drop or rewrite a post, move a date, change the keyword, the DM, the page or an email. That enumeration separates it cleanly from postfjord_get_goal, postfjord_plan_goal, postfjord_launch_goal and the single-post update tools.

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 the operative precondition explicitly ('Only a proposed goal can change; after the launch each part is changed on its own screen') and an exclusion that routes the agent elsewhere once a Flow is live. It also names the source of the payload (postfjord_get_goal) so the agent knows which sibling to call first.

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