kiln_viewer_payload

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

No annotations are present, so the description carries the full burden. It discloses the call context (invoked by the rendered panel, intended as internal support) but says nothing about side effects, whether it is a pure read, token validity/expiry, or failure behavior. For a one-parameter internal read tool this is adequate but thin.

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 short sentences, purpose stated first, then return value, then the do-not-call caveat. Slight overlap between 'Internal support' and 'Called by the rendered panel itself', but nothing is padded and the key warning is not buried.

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 and no annotations, the description should say more about what the payload contains and what a caller sees on a bad token. It does deliver the single most important fact for an agent — that this tool is not meant for direct invocation — which makes it adequate rather than inadequate for an internal helper.

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 0% and the single parameter is titled only 'Artifact Token', so the description must compensate. It partially does by clarifying provenance — the token is one 'the viewer was handed' — but gives no format, source, or lifetime details. This is the minimum viable for a one-param tool.

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 names a specific verb and resource: it 'Returns the viewer-grade mesh payload for a token the viewer was handed.' It also self-identifies as internal support for Kiln's inline 3D viewer, which separates it from the many mesh/render siblings (render_design_mesh, visualize_model, inspect_mesh_view). 'Viewer-grade mesh payload' is jargon, but the operation is unambiguous.

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 explicit when-not guidance: 'Called by the rendered panel itself; not useful to call directly.' That is unusually strong routing signal for an agent deciding whether to invoke it. It does not name an alternative tool an agent should use instead, which keeps it 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.