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

Beyond the annotations (which only assert it is a non-destructive, non-readonly mutation), the description explains the sleep model, the ~30 second cold-start penalty, plan-based quotas, and the refusal contract (names the apps that are on, ask the user which to turn off). That is rich behavioral context an agent cannot get from structured fields.

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?

Front-loaded with the core action and the sleep-vs-always-on tradeoff, then the quota and refusal handling. Every sentence carries information, though the cold-start explanation and the whoami cross-reference make it denser than strictly necessary for a two-parameter toggle.

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?

An output schema exists, so return values need no explanation here. The description still supplies the non-obvious operational context (quota enforcement, refusal semantics, static-site exemption, whoami for limit checks), leaving nothing an agent needs to invoke it correctly.

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% and the always_on schema text already states 'true keeps the app awake... false lets it sleep'. The description restates that meaning in experiential terms (nobody waits) but adds no syntax, default, or format detail beyond the schema, so the 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 opening sentence names a specific verb (keep awake / let sleep) and resource (a spawnpoint app), and the mechanic it governs. It is unmistakably distinct from siblings like deploy_project or terminate_project, and an agent can tell what state it changes without opening the schema.

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-to-use ('when the user wants an app to stay up, or says it is slow to open after a quiet spell') and a clear when-not ('a static site never sleeps and needs none'). It also covers the limit case, directing the agent to turn apps off rather than blindly retrying.

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