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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description usefully adds that the call is project-scoped (never uses the active-project pointer) and that it returns the project identity with the result. It does not disclose what happens to the underlying effect, whether removal is reversible, or how fx ids are obtained, leaving a gap on a mutation tool.

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?

Two sentences, front-loading the scope constraint before the action. No filler, though the scope sentence serves the parameter contract more than the purpose clause.

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?

There is no output schema and the description does say the project identity is returned, and annotations cover the safety profile. However, it omits where fx ids come from (e.g., project_state/editorial map) and whether the removal is undoable, which are meaningful gaps for a mutation tool.

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 50%: project_id is richly documented in the schema, while ids has no schema description. The description only adds 'by fx id' for ids, which confirms the identifier type but not its source or format. Baseline 3 is appropriate since the schema carries most of the explanation for the required scope parameter.

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+resource: 'Remove subject effects and backgrounds by fx id.' This is clear and distinct from siblings like remove_region_effect or remove_stylize. It does not explicitly name the inverse (add_subject_effect), but the resource itself differentiates it well.

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 only usage guidance is the PROJECT-SCOPED scope note (must pass explicit project_id). There is no when-to-use vs. when-not, and no routing to alternatives such as remove_region_effect or remove_screen_takeover when the wrong removal tool is suspected.

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