Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_create_invitation

Idempotent

Invite a person to join an account by generating a single-use token and invitation link, optionally emailing it, with a selected role.

Instructions

Creates a single-use invitation for a person to join the account with the given account_role.

  • token: the acceptance secret, returned once and never readable again, so deliver it to the invitee. invitation_url is the ready-to-use link built from that same token.

  • grants: the companies a MEMBER starts with. Omit it, or send [], to invite them with no company access yet; an explicit null is rejected with 422. Grants are only valid for MEMBER, since OWNER and ADMIN reach every company implicitly.

  • account_role: OWNER cannot be invited. An account has exactly one owner, handed over only through PUT /v1/accounts/{account_id}/owner.

  • send_email: defaults to false, so BeeL sends no email and you deliver the token or invitation_url yourself. Set it to true to have the invitation emailed to invited_email as well.

Endpoint: POST /v1/accounts/{account_id}/invitations

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyYes
account_idYesYour own account, or an account you provisioned. It — not the credential — decides which account the operation acts on; a `403` is returned when you do not reach it, the same response an account that does not exist gets.
idempotency_keyNoOptional idempotency key for this operation. Omit it and one is derived from the request itself, which makes a blind retry safe but also collapses a SECOND, deliberately identical operation into the first for 24 hours. Set it — to an order id, or anything unique per intended operation — whenever you mean to create something that may look identical to what you just created.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.9.0
    • changedInput schema / $defs / CreateInvitationRequest / properties / grants / description
      Previous value: -"Initial grants (only when `account_role` is `MEMBER`). Required: send `[]` to invite with no company access yet (granted later). An explicit `null` is rejected with 400."New value: +"Initial grants (only when `account_role` is `MEMBER`). Omit it, or send `[]`, to invite with no company access yet (granted later). An explicit `null` is rejected with `422` `VALIDATION_ERROR`."
    • addedInput schema / $defs / CreateInvitationRequest / properties / grants / x-field-extra-annotation
      Added value: +"@jakarta.validation.constraints.NotNull"
    • changedInput schema / $defs / CreateInvitationRequest / required
      Previous value: -[
-  "invited_email",
-  "account_role",
-  "grants"
-]New value: +[
+  "invited_email",
+  "account_role"
+]
  2. Changed5 schema fields changedv0.5.0
    • changedInput schema / $defs / AccountRole / description
      Previous value: -"Who administers the account. Independent of `access_level`, which says how much access someone has to a given company (NIF).\n\n`OWNER` — full control, including billing, API keys and transferring ownership. Exactly one per account, so it is never an accepted value when you SET a role (inviting a member or changing one's role): both reject it with `422 OWNER_ROLE_NOT_ASSIGNABLE`. Ownership moves only through `PUT /v1/accounts/{account_id}/owner`.\n`ADMIN` — everything an `OWNER` can do, except transferring ownership.\n`MEMBER` — no account administration. Access to each company is granted individually and reported as `access_level`; a member only sees the companies granted to them."New value: +"Who administers the account. Independent of `access_level`, which says how much access someone has to a given company.\n\n`OWNER` — full control, including billing, API keys and transferring ownership. Exactly one per account, so it is never an accepted value when you SET a role (inviting a member or changing one's role): both reject it with `422 OWNER_ROLE_NOT_ASSIGNABLE`. Ownership moves only through `PUT /v1/accounts/{account_id}/owner`.\n`ADMIN` — everything an `OWNER` can do, except transferring ownership.\n`MEMBER` — no account administration. Access to each company is granted individually and reported as `access_level`; a member only sees the companies granted to them."
    • addedInput schema / $defs / CreateInvitationRequest / additionalProperties
      Added value: +false
    • addedInput schema / $defs / GrantAssignment / additionalProperties
      Added value: +false
    • changedInput schema / $defs / GrantAssignment / properties / company_id / description
      Previous value: -"Company (NIF) identifier within the account."New value: +"Unique identifier (UUID) of the company within the account."
    • addedInput schema / additionalProperties
      Added value: +false
  3. First observedv0.3.1

TDQS

A4/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false, openWorld=true). It discloses that the token is returned once and never readable again, that invitation_url is a ready-to-use link, that an explicit null grants is rejected with 422, that grants are only meaningful for MEMBER, and that send_email defaults to false so the caller must deliver the link. This is exactly the extra behavioral context an agent needs for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose and then uses tight, scannable bullets for each parameter concern. Well-structured, though a few lines (notably the grants null/[] rule) restate the schema almost verbatim, which is minor waste against an otherwise efficient layout.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description compensates by explaining the returned token and invitation_url. For a mutation tool it covers role constraints, grant rules, and email behavior adequately, though it never mentions the idempotency_key parameter or the practical consequence of the idempotentHint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 67% schema coverage, the description still earns its place by adding semantics: what grants means for each role, the omit-vs-[]-vs-null distinction, and the default/effect of send_email. Some of this is duplicated verbatim from the schema, but the role-conditional explanation of grants adds genuine meaning beyond the structured fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Creates a single-use invitation for a person to join the account with the given account_role.' An agent can immediately tell this is the invite-creation tool, distinct from siblings like beel_list_invitations, beel_get_invitation, and beel_delete_invitation. It does not, however, explicitly name an alternative or contrast itself with a sibling, keeping it short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the agent can infer this is the tool for inviting a person, but there is no explicit 'use this when...' guidance, no mention of prerequisites such as needing account-admin rights, and no routing away from alternatives like beel_create_claim_token. Constraints ('OWNER cannot be invited') are given but they govern parameter values, not tool selection.

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

Deploy Server

Other Tools