scratchjr_edit_project

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate mutation. The description adds useful behavioral context: the tool reopens the project after editing, and set_character replaces the whole character. However, it doesn't disclose that edits are batched atomically, whether a failed operation rolls back, or that expectedRevision is an optimistic concurrency guard. With annotations covering the basic safety profile, a 3 is appropriate.

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 with no filler. The key action ('Apply a batch of edits') is front-loaded, the revision requirement is stated early, and the set_character/set_scripts distinction is a valuable disambiguation. It could be slightly more structured by listing operation types, but it earns its place.

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 complex tool with a large operations schema and no output schema, the description is adequate but not complete. It covers the core workflow (get revision, batch edit, reopen) and the most important sibling distinction, but it doesn't mention the available operation actions, the optimistic concurrency semantics of expectedRevision, or what happens on failure. An agent would need to dig into the schema to understand the full operation set, which is a gap for a tool this complex.

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 description coverage is only 33% (projectId and asset have descriptions, but expectedRevision and operations do not). The description compensates partially by explaining expectedRevision ('Supply the revision from get_project') and by clarifying the set_character vs set_scripts distinction. However, it doesn't explain the structure of operations (the oneOf variants) or that operations is a batch array, leaving the agent to parse the large schema. Baseline 3 is fair because the description adds some meaning but doesn't fully compensate for the coverage gap.

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 states a specific verb ('Apply a batch of edits') and resource ('existing project'), and clarifies it reopens the project. It also distinguishes set_character from set_scripts. However, it doesn't enumerate the full set of operations (rename, add_page, set_background, add_character, add_text, set_text, remove_object) that the schema supports, so an agent might not realize the full scope of what 'batch of edits' includes.

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 clear context: use this to apply edits to an existing project, supply the revision from get_project, and use set_scripts instead of set_character when changing only code. It doesn't explicitly state when NOT to use this tool (e.g., for creating a new project, use create_project), but the sibling list and the 'existing project' phrasing imply that boundary.

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