describe_tile

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

No annotations exist, so the description carries full burden. It discloses read-only behavior, the exact return shape, and the nuanced transparency flag semantics: 'true = the tile is see-through and needs an opaque base tile on a lower layer; painting it on layer 0 alone shows the map void.' This is thorough behavioral context.

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 description is dense but structured: first the core decoding behavior, then read-only context, return shape, and optional parameter effect. Each sentence earns its place, though it is slightly longer than minimal.

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?

With no output schema, the description provides the return object fields, which is essential. However, some fields like 'empty' and 'kind' are not defined, leaving minor gaps. For a moderately complex decode tool, this is acceptable but not exhaustive.

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%, so baseline is 3. The description adds beyond the schema by explaining that passing tilesetId triggers PNG inspection and reports 'transparent' and 'transparentPercent', giving meaningful context about the optional parameter's effect.

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 uses the specific verb 'decode' and clearly identifies the resource: a raw RPG Maker MZ tile id. It details the output (tileset sheet A1–A5, B–E, autotile kind/shape/geometry) and frames itself as a read-only inspection helper, distinguishing it from sibling tools like paint_tiles or get_tile_flags.

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 clearly states the context: 'Read-only inspection helper — raw tile ids are opaque integers, this makes one legible.' This implies when to use it (to understand a raw id) but does not explicitly name alternatives or exclusion cases, so it falls short of a 5.

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