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

Annotations already cover the read-only, non-destructive, closed-world profile, and the description goes well beyond them: name sorting, the exact returned fields, the 20-item cap on startedWebsites with kept entries first, the empty-list case for accounts with no sites, and the auth failure behavior. That is exactly the kind of consequence and edge-case detail annotations cannot express.

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 sentences, front-loaded with what is listed and returned, then the startedWebsites scoping rule, then the auth prerequisite. Every clause carries information an agent would otherwise have to discover by calling the tool.

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 and no parameters, the description carries the return-value burden itself and does so, including field names, ordering, truncation limits and the empty-result case. Nothing needed to call this zero-argument tool correctly is missing.

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 tool takes no parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. Its detail about which sites fall into startedWebsites adds useful meaning about the result shape even though it is not parameter-level semantics.

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 gives a specific verb and resource ('Lists the websites in the person's Jaybird Digital account') plus the sort order and returned fields (id, name, live address), and it splits the result into main sites versus startedWebsites. It stops short of naming a sibling such as list_website_files to make the boundary explicit, so an agent must infer that this is the site-level listing rather than a file-level one.

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 supplies concrete operating context: an account connection is required, calling without one triggers a sign-in prompt, and sites created via start_website or opened with an editKey appear under startedWebsites. It does not state any when-not-to-use condition or explicitly route the agent to an alternative, so the guidance is clear but not complete.

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