apps_state

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds the operationally valuable warning that file-transfer success is not evidence the application was applied, which is real behavior guidance beyond the annotations; it does not describe response shape or staleness semantics.

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?

Two sentences, no filler, with the resource scope front-loaded and the corrective instruction second. Every clause carries information.

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 usefully enumerates what is read back (draft, revisions, actual target states) and covers the safety posture via annotations. The remaining gap is the unexplained optional appId, which matters given the tool is also callable with no arguments.

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?

The single parameter appId has 0% schema description coverage and is not required, yet the description never mentions it and does not say what happens when it is omitted (active app assumed) or how it relates to "the active App draft." The scoping of this ambiguous optional parameter is left entirely to inference.

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 (Read) and a clearly enumerated resource set: active App draft, desired/saved revisions, and actual target application states. It is distinguishable from mutation siblings like apps_save/apps_publish, though it never names them or any alternative explicitly.

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?

"Read this after interruption" gives an explicit trigger condition, and "do not infer application from file transfer success" supplies a concrete exclusion/warning about a wrong inference path. It stops short of naming an alternative tool for cross-checking state.

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