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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), it discloses side effects the annotations cannot: invitations are emailed immediately, in-person clients get no account, duplicate-email conflicts are rejected, and the call reaches other people so confirmation is required. It also flags API-key access requirements and a per-tool confirmation toggle.

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-loads the core action and the client-type consequences efficiently. The confirmation requirement is stated twice ('By default you confirm each call...' and 'Reaches other people: confirm with the user before each call'), which is mild redundancy but the sentences otherwise earn their place.

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 mutation tool with no output schema, it covers prerequisites, side effects, and constraints adequately. It does not describe what is returned on success (e.g., the new client identifier), which the agent would otherwise have to discover, but nothing critical for correct invocation 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: email is required only for remote/dual clients, and client_type changes the downstream behavior (invitation vs. no account). This goes beyond the terse schema strings.

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 concrete verb+resource ('Add a client') and immediately qualifies scope by client type, distinguishing it from siblings like truecoach_add_client_to_group and truecoach_list_clients. An agent can tell what is created and under what conditions 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 clear context on when each client_type applies (remote/dual get invitations and accounts, in_person does not) and the constraint that an email already tied to another coach cannot be reused. It stops short of naming alternative tools for related tasks (e.g., adding an existing client to a group), but the when-to-use guidance is strong.

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