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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds one real behavioral detail (resources_only returns inventory) but omits the notable trait the schema references, namely that a normal call polls QA and may start a deployment. That omission matters more than the safety restatement.

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, front-loaded with the core action, and no filler. The trailing "MCP version 2.12" is terse and functional, though it duplicates the schema's mcp_version description rather than adding anything.

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 5-parameter read tool with no output schema, the description covers the main parameters but never characterizes the return shape beyond "deployment state, errors and logs", and leaves the default (non-resources_only) side effects undisclosed. Adequate to make the call, thin for predicting what comes back.

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 100%, so baseline is 3. The description does gloss since as epoch milliseconds and name the resources_only effect, but its claim that "since and limit filter errors" conflicts slightly with the schema, where limit is a shared cap across frontend and backend logs. That introduces mild noise rather than added meaning.

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 opens with a specific verb+resource combo ("check deployment state, errors and logs") scoped to app_id, which is enough to separate it from siblings like get_apps, get_app_versions, and get_upload_status. It stops short of explicitly naming a sibling it is not, so a 4 rather than a 5.

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?

"Use this tool with app_id to check deployment state" implies the calling context, and the resources_only clause hints at a distinct mode of use. But there is no explicit when-to-use versus when-to-use-something-else guidance, and no mention of when to prefer get_app_versions or get_upload_status instead. Usage is inferable, not stated.

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