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

Goes well beyond the annotations: discloses the required idempotency_key, the welcome/set-password email and its pending_user_activation/welcome_email_sent_to signals, the 60-minute JWT lifetime, admin-vs-view permission requirements per container state, per-domain rate-limit semantics, and multi-server next_action.server_name behavior. This is rich operational context the annotations (readOnly/destructive/idempotent hints only) cannot convey.

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?

Long but well-structured: the core behavior and mode branching are front-loaded, followed by a scannable error list. Nearly every sentence carries operational value (recovery URLs, permission names, retry semantics), though the enumeration of returned token fields is somewhat verbose given an output schema exists.

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 15-parameter mutating entry-point tool with an output schema present, the description covers the critical paths, error taxonomy, and permission model well, so return values need not be re-explained. The remaining gap is the large set of undocumented optional parameters (dry_run, framework, agent_client, event_source_system, company), whose semantics an agent must infer.

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 only 20% across 15 parameters, so the description must compensate. It does add meaning for idempotency_key (UUID v7), auth_token (existing-user path), website_url, and the email/name branch, but leaves goal, phone, company, dry_run, framework, agent_client, heard_from, event_source_system, and the onboarding_session_* pair unexplained in both schema and description.

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?

States a specific verb and resource ('Creates or reuses a Tracklution account and the first tracking container for website_url') and immediately distinguishes the two operating modes (new email vs. existing auth_token). An agent can tell what the tool produces 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?

Explicitly says which path applies when ('New email: ...' vs. 'With auth_token instead of email/name: ...') and gives recovery actions for each error condition, including re-running the tool after the user creates a container. It does not, however, position itself against any named sibling (e.g., create_login_link, get_onboarding_session), so routing among siblings is left implicit.

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