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

With no annotations, the description carries the full burden. It discloses behavior beyond simple reading: it works on locked apps if the owner token or API key is provided, and clarifies the lock only affects visitors. It does not mention side effects (like mutation), but as a read operation, the absence is acceptable. It could mention return size limits or pagination but is still strong.

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, both dense with value. The first sentence states the core function, the second adds usage guidance and auth details. No fluff, perfectly front-loaded.

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 read tool with no output schema, it specifies the return is a JSON document. It explains when to use it and auth nuances. It could describe the document structure or mention that it returns user-generated data, but given dynamic data, this is adequate. It fully prepares an agent for invocation.

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 description adds context to secret_token by explaining its role for locked apps and that the owner token or API key suffices. For slug, it implies it identifies the app, which is straightforward. With schema coverage at 50%, the description compensates moderately by clarifying the auth scenario.

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 clearly states the tool returns the JSON document saved by app users, using a specific verb and resource. It distinguishes itself from siblings like get_app (metadata) and set_app_data (write), and adds depth by noting it works on locked apps.

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?

Explicitly advises calling this tool before evolving an app that saves data to understand the actual structure. Also clarifies it works on locked apps with owner credentials, providing clear when-to-use context without needing to contrast with siblings.

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