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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, so the description's added value is the return shape: "Returns a bounded receipt; task_get retrieves all details" — a real signal that output is truncated and follow-up is needed. It also discloses the assignee/reviewer separation constraint beyond the flags; it is silent on whether creation notifies the assignee or what the receipt contains.

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 sentences, front-loaded with the placement decision, then identity rules, then return behavior — no filler. The heavy parenthetical nesting ("parentId alone: the parent's workspace") makes it dense, but every clause carries a real constraint.

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 an 11-parameter creation tool in a workspace/permissions domain, the description nails placement and identity but omits the required `why` rationale field, the audience default, and any notion of what kind/payload do. An output schema exists, so the single return-receipt line is sufficient on that axis, but input-side completeness is only partial.

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 only 55% schema coverage across 11 parameters, the description compensates for the tricky relational ones (workspaceId vs parentId exclusivity, agent:<handle> syntax for assignee/reviewer). But it says nothing about title, due, body, kind, payload, or the mandatory one-sentence `why`, leaving the agent to discover those only in the schema.

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 ("File a task") and immediately disambiguates the two placement modes: directly in a workspace via workspaceId, or as a child of another task via parentId inheriting its workspace. It also names the retrieval counterpart (task_get) so the agent can distinguish create from fetch without opening either schema.

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 concrete operating rules: workspaceId and parentId are mutually exclusive ("parentId alone"), the reviewer must never be the assignee, and agent references require a handle from workspace_load agents. It does not, however, say when to use task_create versus task_propose or task_update, so routing among siblings still relies on the name.

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