Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_create_invitation

Idempotent

Generate a single-use invitation link or token for a person to join an account as admin or member, with optional company access grants and email sending.

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: required. Send the companies a MEMBER starts with, or [] to invite them with no company access yet. 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. 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
  2. First observedv0.3.1

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations, the description discloses critical behavioral traits: the token is returned once and never readable again, invitation_url is derived from it, grants only apply to MEMBER, and send_email defaults to false so no email is sent unless requested. These are exactly the non-obvious behaviors an agent needs to handle the response responsibly.

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?

The description is front-loaded with its core purpose and uses structured bullets for each semantic concern. It is longer than a minimal description, but the length is justified by the number of non-obvious rules. A small amount of redundancy exists, such as repeating send_email's default behavior, but overall it is well organized.

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

Completeness5/5

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

Given the complexity of invitation creation, the lack of an output schema, and the many role/grant edge cases, the description covers all the essential context: return token behavior, invitation_url, grant constraints, owner exclusion, and email delivery. An agent has enough information to call the tool correctly and handle the result appropriately.

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

Parameters5/5

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

The description adds substantial meaning beyond the input schema: it explains the token/invitation_url relationship, clarifies that grants are required and can be an empty array, restricts grants to MEMBER, and warns that OWNER cannot be invited. This directly compensates for the schema's partial coverage and makes correct invocation much more likely.

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

Purpose5/5

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: 'Creates a single-use invitation for a person to join the account.' The qualifiers 'single-use' and the explicit role parameter make the tool's purpose unmistakable, and the endpoint further disambiguates it from the many other create_* siblings.

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

Usage Guidelines4/5

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

The description clearly states what the tool does and gives important context about when it applies, such as 'grants are only valid for MEMBER' and 'OWNER cannot be invited.' It even routes the owner case to an explicit alternative endpoint, but it does not frame the tool choice against siblings like beel_list_invitations or beel_delete_invitation.

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