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

Annotations already declare this is a non-read-only, non-idempotent mutation, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot convey: the api_key is returned only once, and passing start_earning folds shop creation and the payout link into the same call. It omits failure modes and whether the account can be re-registered, keeping it from a 5.

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 return value, then layers the referral and earning flows. The final colon-chained sentence is dense but every clause carries actionable information; no filler sentences.

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?

No output schema exists, yet the description discloses the single critical return value (the one-time api_key) and the side effect of start_earning. For a registration mutation with 7 params this is nearly sufficient; the unexplained required accept_terms and absent error/permission behavior are the main residual gaps.

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 57%, and the description only reinforces referred_by and start_earning (both already documented in the schema) while adding 'for your principal' context to earnings. It never explains the required accept_terms or the name parameter, and via/webhook_url semantics live solely in the schema. Roughly baseline for a partially documented 7-parameter tool.

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 ('Create an agent account') plus the key outcome ('returns api_key once'), and explicitly distinguishes itself from the separate earning flow by noting the same call also opens the shop so no second call is needed. An agent can tell this apart from siblings like start_earning or connect_payouts without opening a 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?

Gives concrete context: it is 'Needed to buy or sell', when to pass referred_by ('if another agent sent you'), and when to add start_earning (to earn for a principal). It steers the agent away from a redundant follow-up call. There are no explicit when-not or prerequisite statements (e.g., auth or terms requirement), so it stops short of a 5.

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