beel_provision_account

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

Annotations mark the operation as non-read-only and non-idempotent, but the description adds crucial context: idempotency by external_ref (contradicting the generic idempotentHint but not conflicting—it explains conditional idempotency), reactivation of previously ended accounts, the default access_level of NONE, and the effect of omitting email. The description also discloses entitlement requirements. It goes far beyond the annotations.

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?

Although lengthy, every sentence serves a purpose: main behavior, variants, edge cases, entitlement. The structure front-loads the claim_token concept and then systematically explains optional fields and their consequences. No repetition or filler; it is as concise as possible given the complexity.

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 complex provisioning operation with an endpoint, multiple optional parameters, and no output schema, the description is complete: it explains what the response contains (claim_token, company_id), prerequisites (entitlement), idempotency, reactivation, and default behaviors. Nothing an agent needs to decide whether and how to call it 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?

The schema has descriptions for many nested fields, but the description adds semantics that the schema alone does not: it explains the two integration branches, the dependency of OPERATE on tax_profile, the idempotency use of external_ref, and the different outcomes (claim_token vs. none). This compensates for the 50% schema coverage by clarifying behavioral implications of each parameter.

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 specific verb and resource: 'Provisions a new account on BeeL'. It clarifies behavior around claim_token, email, tax_profile, and access_level, and distinguishes it from related actions like creating a company or claim token by explicitly stating it provisions an account and sets up invoicing readiness. This leaves no ambiguity about the tool's purpose.

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?

The description gives clear when-to-use guidance: it explains the two integration modes (with email for a holder, without email for no person), when to include a tax_profile (for invoicing readiness), the requirement that OPERATE access demands a tax_profile, and the idempotency/reactivation behavior. It also mentions the manage_accounts entitlement, effectively telling the agent when it can be invoked.

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