MCP Standards

This page defines the platform-wide standards used when exposing Autologyx functionality through Model Context Protocol (MCP) servers.

These standards exist to ensure that MCP tools are predictable, discoverable, and consistently interpreted by AI agents.

Unlike traditional APIs, MCP tools are selected dynamically by AI models. Tool definitions must therefore be optimised primarily for agent understanding rather than human presentation.

The standards described below are based on Autologyx MCP implementations generated from Django REST Framework APIs.

Why standards matter

AI agents select tools based on:

• tool name
• tool description
• input schema
• descriptions of input attributes
• argument structure

Consistent standards improve:

• tool discoverability
• tool selection accuracy
• agent reliability
• interoperability across MCP clients

---

General principles

MCP tools are designed primarily for AI agents.

Users should express intent naturally:

Create an Object Record for customer John Smith.

rather than:

Use create_object_record.

The agent is responsible for selecting the appropriate tool.

For this reason, tool definitions should prioritise:

1. Clear names
2. Accurate descriptions
3. Complete schemas
4. Meaningful attribute descriptions
5. Predictable argument structure

The optional title field may improve presentation but should not be relied upon for tool selection.

---

Tool naming

Naming convention

Tool names should:

• use lowercase letters
• use snake_case
• be action-oriented
• remain stable over time

Recommended format:

<action>_<resource>

Examples:

search_object_classes
get_object_class
create_object_record
update_object_record
assign_task_to_users

MCP title attribute

The MCP title attribute may be used for human-friendly presentation.

Example:

{
  "name": "search_object_classes",
  "title": "Search Object Classes"
}

However, MCP clients and AI models may ignore the title attribute when selecting tools.

Tool discovery and selection should therefore rely primarily on:

• name
• description
• inputSchema

The title attribute should be treated as optional presentation metadata.

---

Tool descriptions

Tool descriptions are one of the most important factors affecting tool selection.

Descriptions should clearly explain:

• what the tool does
• when it should be used
• what kind of result it returns

General guidelines

Descriptions should:

• start with a verb
• be concise
• avoid implementation details where possible
• focus on business purpose rather than technical implementation

Good examples:

Search Object Classes matching given criteria.
Get a single Object Class's details.
Create a new Object Record.
Assign a Task to one or more users.

Poor examples:

Tool for searching.
API endpoint wrapper.
Calls backend service.

Complex tools

If correct usage of a tool requires additional context or instructions, the description should provide sufficient guidance for the AI agent.

Examples may include:

• prerequisites before calling the tool
• required data sources for specific parameters
• follow-up actions after execution
• interpretation of response values

Tool descriptions should contain enough information for an AI agent to use the tool correctly without relying on external documentation.

---

Tool call structure

Autologyx MCP tools are called using the standard MCP tools/call method.

The request should contain:

• method — always tools/call
• params.name — the tool name
• params.arguments — tool arguments

Example:

{
  "method": "tools/call",
  "params": {
    "name": "search_object_classes",
    "arguments": {
      "_alx_claimed_model": ""
    }
  }
}

Arguments object

Tool arguments should follow a predictable structure.

The arguments object may contain:

Attribute	Purpose
kwargs	Path or URL-style parameters identifying a specific resource or context
body	Request payload sent to the underlying API operation
_alx_claimed_model	Audit attribute identifying the AI model executing the tool call

Not every tool requires both kwargs and body.

Read-only detail tools usually require kwargs.

Example:

{
  "method": "tools/call",
  "params": {
    "name": "get_object_class",
    "arguments": {
      "kwargs": {
        "pk": 3
      },
      "_alx_claimed_model": ""
    }
  }
}

Mutation tools usually require body.

Example:

{
  "method": "tools/call",
  "params": {
    "name": "assign_task_to_users",
    "arguments": {
      "body": {
        "task": 1,
        "users": [
          1,
          2
        ]
      },
      "_alx_claimed_model": ""
    }
  }
}

---

Input attribute descriptions

Every input attribute should include a meaningful description.

Attribute descriptions help the AI agent understand:

• the purpose of the field
• expected values
• business meaning
• validation expectations

Good examples:

Primary key of the Object Class.
Identifier of the Task.
List of user IDs assigned to the Task.
Request payload used to update the Object Record.

Poor examples:

Name.
Value.
Field.
Data.

Descriptions should explain the meaning of the attribute rather than simply repeating its name.

Common argument descriptions

The following descriptions should be used consistently where applicable.

Attribute	Description
kwargs	Path or context parameters required to execute the tool.
body	Request payload passed to the underlying API operation.
pk	Primary key of the target resource.
_alx_claimed_model	Exact identifier of the AI model executing the tool call, used for audit and compliance.

---

Audit attributes

Some tools require additional audit information.

Autologyx MCP tools may require the _alx_claimed_model argument.

This attribute is used for:

• auditability
• traceability
• compliance
• operational diagnostics

The _alx_claimed_model attribute should be included in the tool schema when required.

Example:

{
  "_alx_claimed_model": ""
}

The value should identify the AI model executing the tool call. If the model identifier is not available, the caller should follow the behaviour described in the tool schema.

---

Error messages

MCP tools should return errors using a consistent structure.

Error indicator

Tool responses should use the isError attribute to indicate whether execution failed.

Example:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error executing tool: ..."
    }
  ]
}

When execution succeeds:

{
  "isError": false
}

or the attribute may be omitted depending on the MCP implementation.

Error content

Error details should be returned within the content collection.

The content collection should contain one or more objects with:

• type
• text

Example:

{
  "content": [
    {
      "type": "text",
      "text": "Error executing tool: {'detail': [ErrorDetail(string='Stage stage_1 is completed. Owner cannot be changed.', code='invalid')]}"
    }
  ],
  "isError": true
}

REST API errors

When an MCP tool wraps a REST API endpoint, validation and business errors should be propagated from the underlying API whenever possible.

In such cases, the REST API error is returned inside the MCP content[].text field.

This helps maintain consistency between REST and MCP integrations and ensures that the same validation rules are exposed through both interfaces.

---

Tool grouping

Autologyx does not currently define MCP tool grouping standards.

The MCP ecosystem currently provides limited and inconsistent support for tool grouping across clients and AI models.

---

Relationship with REST APIs

Where MCP tools are generated from Django REST Framework endpoints, MCP definitions should remain consistent with the underlying API.

This includes:

• naming conventions
• validation behaviour
• schema definitions
• permission rules
• error messages

Whenever possible, MCP metadata should be derived from the same serializers and endpoint definitions used by the REST API to reduce duplication and prevent inconsistencies.