recover_texture_detail

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

With no annotations, the description carries the burden and does well: it discloses the free-tier cap of 3 textures/month, the Pro tier, that an inline orbit/zoom stage is opened on the result, and that oversized meshes are decimated for the stage. It stops short of stating auth requirements or what the returned artifact is beyond the PNG preview floor.

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 deprecation notice is correctly front-loaded, but the INLINE 3D STAGE paragraph repeats the same fact (inline viewer, orbit/zoom, browser stage link) already stated in the first sentence. Two of the four paragraphs restate stage behavior, which is wasted space on a tool the agent should not call.

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 deprecated alias, the essential decision — don't use it, use keep_painted_detail — is fully covered, along with tier limits and the stage side effect. However, there is no output schema and the description never says what the tool actually produces or how it differs from the successor beyond the name.

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 83% and the description adds no parameter-level information (depth_mm, target_edge_mm, invert, output_path all undocumented in prose). Baseline 3 applies since the schema already describes most parameters, though the semantic meaning of 'invert' and 'target_edge_mm' remains thin.

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's primary message is a deprecation redirect: 'renamed keep_painted_detail; call that.' It never states what the underlying operation does (recovering/keeping painted surface detail), so an agent learns only that this is superseded and that it opens an inline 3D stage. The successor name is concrete, but the tool's own purpose is left implicit in the name.

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?

It gives an explicit when-not-to-use ('DEPRECATED') plus the exact alternative to call ('keep_painted_detail'), which is a real sibling tool. An agent has no ambiguity about routing.

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