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

Annotations only declare it is a non-read-only, open-world, non-idempotent, non-destructive write; the description adds the side effects that matter: an email is sent to the owner with a set-password link, no password is set by the agent, and the widget stays off until sign-in plus card entry. The billing note ('$0 today, nothing charged during the free trial') tells the agent what to expect before the call, which is exactly the beyond-annotation context this tool needs.

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?

Four sentences, front-loaded with the action and return value, then side effects, then eligibility constraints. Every clause carries information the agent needs to either call the tool or warn the user; the billing parenthetical in particular prevents a surprise charge complaint.

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?

There is no output schema, but the description names the two returned artifacts (widget token and embed tag) and the activation condition. Combined with the annotation coverage, an agent knows the auth flow, the side effects, the eligibility limits, and what comes back — nothing material is missing for a 6-parameter mutation tool.

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 schema already documents all six parameters and the baseline is 3. The description still adds a real constraint not present in the schema — that disposable, test, and placeholder values for owner_email are refused — which changes how the agent should source that argument. The other five parameters get no extra treatment, so it stays below a 5.

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 a contractor account') and goes further by naming the return payload ('widget token and embed tag'), which an agent can act on immediately. It also disambiguates from the sibling get_install_snippet by framing it as the follow-up step rather than a competing action.

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 gates usage: only when the person owns the business or asked for the setup, and only with a real business email. It also states a hard exclusion ('test, disposable and placeholder addresses are refused') and points to get_install_snippet as the next tool, so the agent knows both when to call it and what to do after.

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