Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_list_products

Read-onlyIdempotent

Retrieves a paginated list of a company's products and services, with optional search and filters by name, code, category, status, and price.

Instructions

Returns a paginated list of the products/services of this company, with optional filters.

  • q: searching is done on this collection, there is no separate search path. q matches the name, the code and the description, so it returns at least everything the withdrawn GET /v1/products/search returned, in the paginated envelope of this list.

BeeL API endpoint: GET /v1/companies/{company_id}/products (reference: https://docs.beel.es)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company_id": "<company_id>"
    },
    "name": "beel_list_products"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoSearch by name, code or description
codeNoFilter by code (partial search)
nameNoFilter by name (partial search case-insensitive)
pageNoPage number, starting at 1. The response echoes it back as `pagination.current_page`.
limitNoHow many items to return per page. The response echoes it back as `pagination.items_per_page`.
activeNoFilter by active/inactive status
sort_byNoField to sort byname
categoryNoFilter by product category
max_priceNoMaximum price
min_priceNoMinimum price
company_idYesUnique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
sort_orderNoSort order directionasc

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.10.0
    • addedInput schema / properties / category / type
      Added value: +"string"
    • addedInput schema / properties / sort_by / type
      Added value: +"string"
    • addedInput schema / properties / sort_order / type
      Added value: +"string"
  2. Changed1 schema field changedv0.9.0
    • changedInput schema / $defs / ProductSortBy / description
      Previous value: -"Product field the list is ordered by."New value: +"Product field the list is ordered by.\n\n- `name`: product name.\n- `code`: product code.\n- `category`: product category.\n- `default_price`: default unit price.\n- `created_at`: creation instant.\n"
  3. Changed5 schema fields changedv0.5.0
    • removedInput schema / $defs / ProductCategory / example
      Removed value: -"CONSULTING"
    • removedInput schema / $defs / ProductSortBy / example
      Removed value: -"name"
    • removedInput schema / $defs / SortOrder / example
      Removed value: -"desc"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / company_id / description
      Previous value: -"NIF (company) the operation acts on. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A NIF you do not reach answers `403`, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed."New value: +"Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed."
  4. First observedv0.3.1

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered and the bar is lower. The description adds that results come back in a paginated envelope, but says nothing about the item shape, ordering defaults, or what an empty result means. Adequate, not rich.

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?

Purpose is front-loaded in one sentence, followed by a scoped bullet on the one non-obvious parameter and an endpoint reference. The `q` bullet is somewhat long and spends words on a withdrawn endpoint, which is history rather than actionable guidance, but nothing is redundant enough to obscure the definition.

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?

With 12 parameters at full schema coverage and no output schema, the burden on the description is light. It correctly conveys that this is a filtered, paginated list and that search lives here, which is what an agent needs to call it; only the returned product fields are left implicit.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains q, filters, paging, sorting and company_id semantics in detail. The description only restates the `q` matching fields and adds the equivalence-with-withdrawn-search guarantee, which is marginal added meaning.

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?

The first sentence states a specific verb and resource ('Returns a paginated list of the products/services of this company') and scopes it to one company. It is clearly a collection-read, distinguishable from beel_get_product (single fetch) and beel_patch_product (mutation), though it never names those siblings explicitly.

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 `q` bullet gives explicit routing guidance: search happens on this collection, there is no separate search path, and it matches name, code and description. That prevents an agent from hunting for a dedicated search tool. It stops short of saying when to prefer `q` versus the discrete `code`/`name` filters.

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