Claude Mods API: add custom commands and tools

The Claude Mods API allows you to add a user command or tool that Claude can call. A command is suitable for explicit consultation; a tool serves when that function must be available in the agent's reasoning. The choice of input determines description, input, error handling, and function authority. Official Guide Mods API.

This guide is verified on 9 October 2026 and uses a read-only designed example: see title and status of a dummy ticket. It is not a customer integration performed. For plugin packaging follow the first mod TypeScript; to choose between different mechanisms parts from the guide to Mods by Claude.

When is a command enough and when is a tool needed?

If a person wants to open a state or consult a specific data, a command keeps the choice explicit. The user decides when to run it and which topic to go through. It is a good first option for a new function, because its use is easily recognizable in the workflow. It does not oblige to make the function available in every situation of the model.

A tool is best suited when Claude must be able to get that data to complete a task. Its description must therefore clarify not only what it does, but when it is relevant. 'Manage ticket' is too wide for a consultation that returns title and status. ‘Law title and status of a ticket by identification, without changing it’ is a more useful contract.

The two entries may recall the same reference core, but they must not duplicate its rules. Authorization belongs to that core or to the reliable service that reads the data. If a rule lives only in the text of the description, a different form of invocation may not comply with it. The guide to AI agents helps to recognize the difference between education and exposed ability.

How to design a lookup ticket before registering it?

Write down four conditions: which identifier you accept, which source you consult, which fields you return, and what effect you exclude. In our designed example the ticket is synthetic, the function is read-only and the result contains title and status. It does not include attachments, conversations or personal details. A small output is easier to verify and does not introduce data without a need.

Then define three different outcomes. Success means the authorized record has been found. Not found means the consultation worked but that record is not there. Error means that the function could not verify the data. Returning ‘no tickets’ when the service is unresponsive would turn a technical problem into false information.

The first test doesn't need a corporate network. You can build fixture with a present identifier, an absent one, and an error response. Synthetic names must be recognizable as examples. Only after verifying this contract it is advisable to connect the real service, with suitable accesses and policies. The Guide to AI API provides the framework of the boundary between applications.

Which JSON Scheme to use for a small input?

An example of designed application scheme, not a full handler, is:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identificativo del ticket sintetico da consultare"
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

This contract requires a string and limits the expected fields. It does not certify that the identifier is authorised, existing or without consequences in the linked service. Once the input is received, the function must control the value according to the system rules. Valid JSON syntax is the starting point, not the completion of integration.

Avoid inserting a field into the input that allows the model to freely choose the level of authorization or organization to impersonate. The identity and perimeter of the access must come from a reliable context. The model can ask for a given; it must not be able to turn a parameter into a privilege. Even a read-only function can expose confidential information.

Registration and canonical names: what to check?

The guide records commands and tools at the start of the session. The commands are managed on command.run; the tools on filtered calls for the canonical name. A tool registered by a plugin called ufficio-demo, with name ticket, is identified in the form mcp__ufficio-demo__ticket. It is an example of nomenclature, not an external server created by this guide. API Mods: commands and tools.

The prefix can be confusing: an MCP-like name does not mean that the package is a tutorial to build an MCP server. The boundary of the mod remains that of Claude Code. If the function is to be reused by multiple applications, it may be appropriate to expose it through a separate service and leave the mod the local input role.

For commands, choose a name that does not match those already present. The documentation describes registration errors for busy names. A collision should be treated as a recognizable error: it must not make the command appear to be available while it is missing. Before deciding on the name, check the inputs of the real environment and maintain a stable identity in the README.

When to use immediate and isDeferred?

immediate: true allows a command to be executed while Claude works. This necessitates a state question: does the function read data that could change during the shift? If you open only one information panel the problem may be limited; if you edit a shared state you must define order and consistency. Don't add this option to make each command seem faster.

For tools, isDeferred has a version 2.1.293 or later boundary. The release describes the possibility of immediately exposing the scheme with isDeferred: false. Check the field in local types before using it and write down the requirement for the team. Official Release 2.1.293.

Do not derive a universal advantage from a choice of exposure. An always available feature can help a task or introduce a useless option. The decision depends on the need, description and frequency of use. The verification criterion is whether Claude chooses the tool in the designed situations, not a general promise of lower cost or better reasoning.

How to make mistakes useful without exposing too much?

The message must help decide the next step. ‘Missing ID’ suggests correcting the input. "Data not available" suggests checking the source. ‘Access not allowed’ requires an authorized manager or path. Avoid a single ambiguous text for all errors, but do not report unnecessary tokens, secret configurations, or internal details.

The positive result should be equally measured. In the designed lookup it is enough to indicate identification, title and status, with the meaning of the data and any useful time reference. Don't add an invented summary of conversations if the function doesn't read them. If the record contains external text, consider it a data to be treated in its context, not a new instruction to the plugin.

A check of the lookup result

Check that a present ticket returns only the required fields. An absent identifier must be distinguished from a network error. A denied access must not reveal the contents of the record. A malformed source response must produce a recognizable error. Finally, it checks that no case turns the consultation into an amendment.

The Guide to test a mod allows you to design these cases with stubs. Before connecting company data read also AI and Data Security. «Read-only» describes an effect, does not demonstrate compliance with any permission or the correctness of the destination.

Does a consultation have to use cache or always read the source?

The answer depends on the decision that the data is used. A title can change little, while an operating state can change just during the task. If the project uses a cache, the result must make the freshness of the data and the refresh policy understandable. Do not invent an API field to solve the issue: first define the application contract and check which methods of the installed version support it.

A designed example can distinguish ‘read status now’, ‘last read available’ and ‘unverified data’. The model must be able to interpret the difference without turning an old answer into certainty. The test then includes a changed fixture and an unavailable source. If the requirement requires an updated data, do not silently return the old value as a success.

The same attention is given to the user command. A person can call him back twice and expect a new consultation; if the behavior is different, the description must clarify it. Preserving a value can be useful, but it makes it necessary to decide who invalidates it and when. A mod with network and state should not hide this responsibility inside a shortcut. For a first version, a small reading with explicit outcomes may be easier to verify than an introduced cache without a measured need.

Two hypothetical scenarios: internal assistance and development teams

Hypothetical example: an SME from Vicenza consults internal technical tickets. The manager wants a developer to be able to recall a state without opening another system. Start with a user command and synthetic fixtures. The result does not include customer name or attachments, because to decide on the next step all you need is a technical title and status.

After the test, the team evaluates a tool for Claude, but limits its promise to the same consultation. It does not add ticket closure or priority change in the first version. If a request requires an action, the component leaves it to the already authorized workflow. The read-only contract remains small and understandable even for those who approve the plugin.

Hypothetical example: a software house in Bari connects its tracker. The tool must help Claude check a task's requirement before editing. The manager defines which projects are accessible through credentials and service, without delegating to the tool parameter the choice of privileges. Evidence includes absentee ticket, unauthorized project, and temporarily unavailable source.

The team does not consider the result a complete specification if the tracker contains ambiguous instructions. The reviewer compares the data with the project requirement and with the diff. To distribute the feature keep version, schema, and test cases in the team source, following Mods and Organizational Security.

What errors turn a small function into a risk?

The first is to display a tool with a broader description of its capabilities. The second is to use the scheme as an authorization. The third is to confuse absence of the record with source error. The fourth is filtering the visible name instead of the canonical. The fifth is introducing scriptures into a function presented as consultation.

Another trap is to assume that the tool call policy protects every direct call of the mod. Mods are not sandboxed; their accesses to filesystems and processes have a boundary to examine. Security of plugins. The review must compare the code with the promise, not settle for the name chosen for the tool.

How to apply the Mods API to a business integration?

Start with a precise consultation, with minimal data and a source owner. Define who invokes the function, what identity authorizes access, and what outcomes are possible. Then build synthetic evidence and a distribution procedure. The Diagnosis of Mods helps when the recorded function does not appear or the behavior differs between machines.

If your team is to bring in an internal consultation within Claude Code, the service of AI agents can help you choose the boundary between local function and shared integration. AI API and Claude Code complete the decision before adding capabilities that the agent has not yet to use.