create-planner-plan

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description's added value is what it says about irreversibility ('the container cannot be changed later'), the membership permission requirement, and the return value (the new plan id). It does not mention the confirm gate, but that param is documented in the schema, so the gap is minor.

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?

Front-loaded with the action, then a compact tip block that carries the highest-value details (body shape, permission, immutability, return value). The second half is a dense run of clauses in one paragraph that would scan better as bullets, but no sentence is 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?

For a create tool with no output schema, the description supplies the essentials an agent needs to invoke it correctly: required body shape, the identity that must be supplied, the permission precondition, the irreversible container choice, and what the call returns. Nothing critical is left to inference.

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 75% schema coverage the baseline is 3, and the description beats it by giving a concrete body exemplar ({"container": {"url": .../groups/{group-id}}, "title": "..."}) and clarifying that a team's group id is the team id. That disambiguates the container.url vs containerId ambiguity the schema leaves open (both are marked Optional).

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 new plannerPlan object') and immediately scopes it to a group/team container, which separates it from update-planner-plan and get-planner-plan in the sibling list. An agent can tell from the first line plus the container tip that this is plan creation, not bucket/task creation.

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 real preconditions: the signed-in user must be a member of the target group, and for a team the group id is the team id. It also routes the agent onward ('to show the plan in a channel, add a Planner tab with create-channel-tab'), but never explicitly contrasts with update-planner-plan or list-group-planner-plans, so there is no stated when-not-to-use.

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