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

No annotations are provided, so the description carries the full burden. It discloses one key behavioral consequence: turning maintain off does not delete or revoke already cloned content, only stops future repeat get_scaffold access after the current Maintain billing period. It does not elaborate on rotate behavior (e.g., immediate invalidation of old key) beyond what the schema already says, nor on other potential side effects, permissions, or reversibility. This is partial but useful transparency.

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?

The description is two sentences with no redundancy. The primary purpose is front-loaded ('Turns Maintain on/off...'), followed by a single important behavioral note. Every word contributes to understanding, making it highly efficient and well-structured.

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 simple set operation with three parameters and no output schema, the description covers the main points: what it does (maintain on/off, rotate key), how to identify the project (projectid scoped to account), and a key consequence (maintain off effect). It does not describe the exact response format or error conditions, but these are less critical for a mutation tool. It is sufficiently complete for an agent to use correctly without needing additional context.

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 67% (rotate and projectid have descriptions, maintain has none). The tool description compensates by explaining maintain's effect ('Turns Maintain on/off') and adding emphasis on projectid being scoped to the authenticated account. This adds meaning beyond the schema for the undocumented maintain parameter and clarifies usage context. It does not add much for rotate beyond what the schema already provides, but overall it adds value.

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's purpose: 'Turns Maintain on/off for one of this account's projects and/or rotates its project key.' This specifies the action (turning Maintain on/off, rotating key), the resource (a project of the authenticated account), and distinguishes it from sibling set_* tools (set_adminpageset, set_github, set_siteprofile) by naming the project resource 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?

The description gives clear context on when to use the tool: to change Maintain status or rotate key for a specific project, identified by projectid scoped to the authenticated account. It also notes the consequence of turning maintain off (stops future get_scaffold access after billing period). However, it does not explicitly mention alternatives (e.g., use get_projects to list projects) or when not to use it, so it lacks an explicit when/when-not statement.

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