Tools

Cademí MCP offers 396 tools: 5 composite tools that answer common questions in one call, and 391 tools that each call one operation of the Cademí API v3, release 3.4.7. The full list, with the permissions and annotations of each tool, is in the tool catalog.

Composite tools

All five are read-only. They never change data: when a fix exists, student_access_context suggests the tool to use, and the assistant calls it separately, with your approval.

How students and products are found

Composite tools take a student as a public ID (usr_...), an e-mail address, or a name, and a product as a public ID (prd_...) or a name. You never need to look up an ID first.

• Public ID. The student or product is retrieved directly.
• E-mail. The tool searches the account's students and keeps the one whose e-mail matches exactly, ignoring case.
• Name. The tool searches by the name and compares it with up to 20 results. Results whose name matches exactly, ignoring case, are kept. If none matches exactly, all results are kept.

When exactly one student or product is left, the tool uses it. When none is left, the tool returns RESOURCE_NOT_FOUND. When several are left, it returns AMBIGUOUS_REFERENCE instead of guessing, with up to 10 candidates in details.candidates, each with its id, name, and, for students, email:

{
  "error": {
    "code": "AMBIGUOUS_REFERENCE",
    "message": "2 students match \"Maria\". Ask the user which one they mean, then call again with its ID.",
    "retryable": false,
    "details": {
      "candidates": [
        { "id": "usr_01J8Z6", "name": "Maria Souza", "email": "[email protected]" },
        { "id": "usr_01J8Z7", "name": "Maria Lima", "email": "[email protected]" }
      ]
    }
  }
}

The assistant then asks you which one you mean and calls the tool again with its ID.

Partial results

A composite tool reads several API operations. When an optional part cannot be read, for example because the administrator lacks the permission for it, the tool still answers: that part is null, and an entry in warnings explains what is missing, with the error_code and the API request_id when there is one. When a required part fails, the whole call fails with an error. Authorization and capacity errors always fail the whole call.

Lists that a composite tool reads in several pages have a complete field. complete: false means there was more data than the tool reads: use the corresponding list tool with filters to see the rest.

student_context

Everything about one student, as the first step of a question about them.

Permissions: users.read. Enrollments and product access also need enrollments.read; without it, they come back null with a warning.

student_access_context

Whether one student can access one product, and why. Use it for questions such as "why can't João access the Marketing course?" or "why doesn't Maria see module 3?".

The API decides whether the student has access: diagnosis.can_access is the API's has_access. The diagnosis explains that verdict with the reason codes below. Each reason has a severity: blocking explains why there is no access, warning points to something that needs attention, and info gives context. Each suggested action names the tool that fixes the problem and what it does, such as users_enrollments_create to grant a manual enrollment.

Permissions: users.read and products.read to find the student and the product, and enrollments.read for the access verdict. The enrollments and the release calendar also need enrollments.read, and progress needs progress.read; without them, those parts come back null with a warning.

Access reason codes

Enrollments that come from a sale or a subscription are managed by the payment gateway, so the suggested actions for revoked, suspended, and expired enrollments apply only to manual enrollments.

product_context

An overview of a product, to understand it before answering questions about it or changing it.

Permissions: products.read. Deliveries also need deliveries.read, and access schedules need access_schedules.read; without them, those parts come back null with a warning.

product_structure

The complete content tree of a product: every module and lesson, nested and in order, with its status and totals.

The tree goes down four levels, and the tool expands up to 150 modules. A module that was not expanded has children_complete: false: read its content with modules_content_list.

Permissions: products.read, and modules.read to expand modules. Without modules.read, modules come back with children_complete: false and a warning.

instance_overview

The account this connection works on. Use it to confirm the account before making changes, or for questions about the account's status and limits.

This tool takes no input.

Permissions: account.read. Usage also needs usage.read; without it, usage comes back null with a warning.

Tools per operation

Every operation of the API v3 has a tool, generated from the API contract, except the four listed in Operations without a tool. The tool name is the operation ID with dots replaced by underscores:

The tool title is the operation summary, and the description adds the operation's description, how to page, whether the tool changes or removes data, the body fields, and the permission it requires. Some descriptions point to a composite tool that answers the same question in one call. For the parameters and fields of each operation, see the API reference.

Input

Fields outside the operation's schema are rejected.

Output

A list tool returns one page per call. Use the operation's filters to narrow the results instead of paging through a whole collection.

Operations without a tool

The API release 3.4.7 has 395 operations. Four of them have no tool on purpose:

Annotations

Every tool carries MCP annotations, so your client can tell reads from changes and ask for your approval before a change:

The annotations describe the tool. The API still checks every call against the administrator's permissions (Authorization and permissions).

Each tool also publishes metadata in _meta:

Results

A successful call returns the result as structuredContent and the same JSON as text. Composite tools declare an output schema.

When a result is larger than the response size limit, it is shortened and says so with truncated: true and a truncation object that explains what was omitted and how to get the rest. A failed call returns an error with a stable code. See Errors and limits.