Capture stamp

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

With no annotations, the description carries the whole burden and does so: it discloses what gets captured (all six layers, shadow bits, events), the includeEvents default, write/replace semantics gated on overwrite, and the changeset staging interaction with commit_changeset. The .gitignore advice adds operational context an agent would otherwise have to guess.

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?

The core operation, its destination, and the sibling reference are front-loaded, and nearly every clause carries information. The trailing .gitignore sentence is useful but is the one piece that could be trimmed without harming invocation correctness.

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 unannotated, no-output-schema, eight-parameter write tool this is complete: validation limits, name syntax, overwrite policy, changeset staging behavior, and destination path are all stated. Nothing an agent needs to call it correctly is missing.

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?

At 38% schema coverage the description must compensate, and it does for the most consequential parameters: width/height bounds of 1-64, the in-map constraint, the name character rules and 1-64 length, overwrite replacement rule, and includeEvents default true. x, y and mapId get no explanation beyond their names, leaving a small residual 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?

States a specific verb and resource ('Save a rectangle of a map as a reusable stamp') plus the exact on-disk target path, and immediately contrasts with the sibling paste operation. An agent can distinguish capture_stamp from place_stamp and list_stamps without opening any 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?

Explicitly routes to place_stamp for pasting and adds a concrete condition ('same tileset'), and the overwrite/gitignore notes clarify follow-up behavior. It does not state when capturing is a poor choice (e.g. large regions, cross-tileset reuse), so it stops just short of full when/when-not coverage.

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