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

The description discloses several non-obvious behaviors beyond the sparse annotations: a routing pass selects applicable scenes, the call is synchronous with a few seconds per scene, there is a hard limit of 10 scenes, and the return value is per-scene results with summary and mutation_count. This fully carries the behavioral burden since all annotations are false.

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, each earning its place: the first states purpose, the second states the routing constraint and alternative, the third states behavior and return shape. The most important scoping information is front-loaded.

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 tool with no output schema and all-false annotations, the description covers purpose, constraints (10 scenes), synchronous timing, and return fields. It could additionally mention error cases or what happens when no scenes match, but it is already sufficient for an agent to call it correctly.

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%, with both parameters already well-described: 'message' has natural-language examples and 'project_id' explains its origin. The description reinforces that 'message' is project-wide in scope but does not add any new parameter-level detail beyond the schema, so the baseline of 3 applies.

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 opens with a specific verb and resource: 'Apply a project-WIDE director note', with concrete examples like 'make the intro punchier'. It also differentiates itself from the sibling 'director_note' by explicitly framing the scope as project-wide, so an agent can tell them apart immediately.

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?

The description gives a clear condition for when to repeat calls or fall back to the alternative: 'at most 10 scenes per call, so a change touching more needs repeat calls or per-scene director_note'. It identifies the sibling tool and a limiting constraint, though it could be more explicit about preferring per-scene director_note for single-scene edits.

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