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

Annotations already declare readOnlyHint=false, openWorldHint=false and destructiveHint=true, and the description adds nothing on top of that envelope — notably it does not explain why a creation tool is flagged destructive or whether creation overwrites an existing team with the same name. The one behavioral nugget (projectId is derived from credentials) is useful but thin. No contradiction with the annotations exists.

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 short sentences with no padding and the key constraint (projectId provenance) placed early, so structure is reasonable. However 'Fields: oneuptime_describe_resource' is cryptic enough to read as a dangling fragment rather than an actionable instruction, wasting the second sentence's slot.

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 write tool with four parameters including a nested object, 25% schema coverage, a destructive annotation and no output schema, the description should cover customFields shape and what is returned on success. None of that is present, and the cross-reference to oneuptime_describe_resource does not adequately substitute.

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 only 25%: name is documented in the schema, while projectId, description and the nested customFields object are not. The description compensates for exactly one of these (projectId comes from credentials), leaving customFields — the only nested object — completely unexplained, and 'Fields: oneuptime_describe_resource' offloads the remainder to another tool instead of supplying 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?

"Create a Team" restates the tool name and title verbatim and adds no specificity about what a team is, what it is scoped to, or how it differs from update_team/list_teams. The only content beyond the tautology is a note about where projectId comes from, which is parameter information rather than purpose. An agent learns nothing it could not infer from the name alone.

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?

There is no when-to-use guidance: no statement of prerequisites beyond the partial hint that projectId comes from credentials, no mention of calling list_teams first to avoid duplicates, and no contrast with update_team or get_team. The pointer to oneuptime_describe_resource is a generic deferral rather than guidance for invoking this tool.

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