scene_info

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior the annotations cannot: the exact scope of what is returned, the units of the geometric values, and that every node type is enumerated. With no output schema present, this return-shape disclosure is the only place an agent learns the response format, which is genuinely useful — though it omits any sizing/verbosity guidance beyond the schema's max_nodes cap.

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?

It is one front-loaded sentence that leads with the verb and scope before enumerating fields. The field list is long but every item is informative given the absence of an output schema. No filler or hedging.

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 three-optional-parameter read tool with full schema coverage, no output schema and complete annotation coverage, the description supplies the one thing structured data lacks: the returned field set and units. Remaining gaps (output nesting, cost on large scenes) are minor for a read-only inspection call.

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 100%, so max_nodes, include_bones and include_hidden are already documented in the schema, and the description adds nothing about them. It does clarify output semantics (position in cm, rotation in degrees), but those are return-value facts, not parameter meaning. Baseline 3 applies.

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 has a specific verb ("Describes") and a specific resource ("the open scene"), and enumerates exactly what the payload contains: file, frames, figures, props, cameras, lights with parent, position, rotation, scale and bounding box. That is far beyond a restatement of the name. What it does not do is distinguish itself from the sibling figure_info, which by name appears to read a single figure's data; the agent must infer that scene_info is the whole-scene variant.

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?

Usage is only implied by "the open scene" — there is no explicit statement of when to call this versus figure_info, nor any prerequisite such as a scene needing to be open first. No exclusions or alternatives are named. It is adequate for an obvious inspection tool but an agent gets no routing guidance from the text.

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