Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cyoda Calculation Node MCP create a new entity of type Contact with name 'John Doe'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A comprehensive application framework for building calculation nodes within the Cyoda platform. This project provides a structured foundation for developing entity-driven applications with workflow automation, built on the asynchronous Quart web framework.
This is a Cyoda Calculation Node - a specialized application that:
Manages entities (structured data models) within the Cyoda ecosystem
Executes workflows (finite-state machines) to process entity state transitions
Integrates with the Cyoda platform via gRPC for seamless data synchronization
Provides REST APIs for entity management and workflow operations
Supports AI assistant integration through the Model Context Protocol (MCP)
Related MCP server: coda-mcp-server
├── application/ # Your application code (entities, workflows, routes)
├── common/ # Shared infrastructure (auth, config, gRPC, repository)
├── cyoda_mcp/ # MCP server for AI assistant integration
├── example_application/ # Reference implementation
├── services/ # Service configuration and initialization
└── tests/ # Comprehensive test suiteapplication/ - Your custom business logic
entity/ - Entity definitions and workflow implementations
routes/ - REST API endpoints
processor/ - Custom processors and criteria functions
cyoda_mcp/ - MCP server for AI integration
See cyoda_mcp/README.md for MCP server documentation
common/ - Shared infrastructure (do not modify unless necessary)
auth/ - Authentication and token management
config/ - Configuration and environment variables
grpc_client/ - Cyoda gRPC integration
repository/ - Data access layer
service/ - Business logic interfaces
example_application/ - Reference implementation showing best practices
# Clone the repository
git clone <repository-url>
cd mcp-cyoda-quart-app
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtexport CYODA_CLIENT_ID="your-client-id"
export CYODA_CLIENT_SECRET="your-client-secret"
export CYODA_HOST="client-<id>.eu.cyoda.net"# Run the application server
python -m application.app
# Or run the MCP server for AI integration
python -m cyoda_mcpThis project includes a Model Context Protocol (MCP) server that enables AI assistants to interact with your Cyoda application.
For complete MCP server documentation, see: cyoda_mcp/README.md
# Install globally
pipx install mcp-cyoda
# Run the server
mcp-cyoda# Run all quality checks
python -m black . && python -m isort . && python -m mypy . && python -m flake8 . && python -m bandit -r .
# Run tests
python -m pytest tests/ -vSee CONTRIBUTING.md for detailed contribution guidelines.
CONTRIBUTING.md - Contribution guidelines and development workflow
AI_TESTING_GUIDE.md - Testing with AI assistants
CYODA_E2E_TESTING_GUIDE.md - End-to-end testing procedures
cyoda_mcp/README.md - MCP server documentation
docs/ - Architecture and design documentation
Cyoda Platform: https://ai.cyoda.net
Documentation: https://docs.cyoda.net
Issues: GitHub Issues
MIT License - See LICENSE for details
Retrieve an edge message by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | The ID of the message to retrieve |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only says 'Retrieve' with no mention of idempotency, read-only nature, error behavior (e.g., if ID not found), or permissions. This is insufficient for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no unnecessary words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, output schema present), the description is mostly adequate. However, it lacks any mention of error handling or use case context. With low complexity, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (message_id described). The description adds no extra meaning beyond the schema, which is acceptable. Baseline 3 is appropriate as the schema already documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve an edge message by ID', which is a specific verb and resource. It distinguishes itself from sibling tools like edge_message_send_edge_message_tool and entity retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a message ID, but provides no explicit guidance on when to use this vs alternatives (e.g., search tools), nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a new edge message.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | Message subject | |
| content | Yes | Message content as dictionary | |
| message_id | No | Optional message ID | |
| user_id | No | Optional user ID | |
| recipient | No | Optional recipient | |
| reply_to | No | Optional reply-to address | |
| correlation_id | No | Optional correlation ID | |
| content_encoding | No | Optional content encoding | |
| content_length | No | Optional content length | |
| content_type | No | Content type (default: application/json) | application/json |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'send', implying mutation, but lacks details on success behavior, authentication, or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words, though it is brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and an output schema, the one-sentence description is insufficient; it lacks context about the messaging system and return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters; the tool description adds no additional meaning beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'send' and the resource 'edge message', distinguishing it from the sibling get tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new entity of a given model.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_model | Yes | The type of entity to create | |
| entity_data | Yes | The data for the new entity | |
| entity_version | No | The entity model version | 1 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose all behavioral traits. It only says 'Create a new entity', without mentioning side effects, permissions, idempotency, or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but too minimal; it provides the verb and resource but lacks detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters, nested objects, and an output schema, the description should explain return values or behavior; it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a description, but the tool description adds no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new entity for a given model, but it does not differentiate from sibling tools like update or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; the description lacks any context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an entity by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_model | Yes | The type of entity to delete | |
| entity_id | Yes | The technical UUID of the entity | |
| entity_version | No | The entity model version | 1 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden, but only states 'Delete an entity by ID' with no mention of side effects, permissions, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no waste. Could be slightly more descriptive but appropriate for a simple action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values not needed. However, a delete tool should hint at success/failure or consequences, which is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Delete' and the resource 'entity', and the sibling tools include create, get, update, list, making it distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives, no prerequisites or context for deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single entity by its technical ID.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_model | Yes | The type of entity (e.g., 'laureate', 'subscriber', 'job') | |
| entity_id | Yes | The technical UUID of the entity | |
| entity_version | No | The entity model version (default: from config) | 1 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the operation but does not disclose side effects, permissions, rate limits, or that it is a read-only operation. For a simple retrieval, this is minimally acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every word is necessary to convey the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool, the description is nearly complete. It does not explain error cases or return values, but the presence of an output schema helps fill those gaps. Still, it could mention that the entity is returned in full.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; each parameter (entity_model, entity_id, entity_version) already has a description in the schema. The tool description adds no additional meaning beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve a single entity by its technical ID' clearly states the verb 'Retrieve', the resource 'a single entity', and the method 'by its technical ID'. This distinguishes it from sibling tools like entity_create_entity_tool, entity_delete_entity_tool, and entity_list_entities_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the technical ID is known, but does not explicitly state when to use this tool versus alternatives like search tools for unknown IDs. No guidance on exclusions or alternatives is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all entities of a specific type.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_model | Yes | The type of entity to list | |
| entity_version | No | The entity model version | 1 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral aspects such as pagination, sorting, limits, or error handling when the entity type is invalid. The agent has no insight into the tool's side effects or output characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the core action. It is appropriately concise for a straightforward list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 parameters, simple list operation) and the presence of an output schema, the description adequately conveys the tool's purpose. It lacks details on return format but the output schema may compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the description does not need to add much. However, it adds no extra context about the format of entity_model or version beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all entities of a specific type, which distinguishes it from sibling tools that get, create, or update a single entity. However, it could be more precise about what constitutes 'entity type'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like search_find_all or entity_get_entity_tool. There is no mention of prerequisites or scenarios where this tool is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing entity.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_model | Yes | The type of entity to update | |
| entity_id | Yes | The technical UUID of the entity | |
| entity_data | Yes | The updated data for the entity | |
| entity_version | No | The entity model version | 1 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose whether updates are partial or full, required permissions, or side effects. The description carries the full burden but fails to provide behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks any structure or emphasis; it could be considered under-specified rather than efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, an output schema, and sibling tools, the description is too minimal; it does not explain expected updates, return value, or error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description adds no extra meaning beyond the schema, so baseline 3 is appropriate despite no param-specific elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing entity' uses a clear verb and resource, distinguishing it from sibling tools like entity_create_entity_tool and entity_delete_entity_tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; no context about prerequisites, limitations, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all entities of a specific type using entity_service.find_all().
| Name | Required | Description | Default |
|---|---|---|---|
| entity_model | Yes | The type of entity to retrieve (e.g., 'laureate', 'subscriber', 'job') | |
| entity_version | No | The entity model version (default: from config) | 1 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose any behavioral traits such as read-only nature, pagination, rate limits, or potential side effects. The agent has no insight into the tool's behavior beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it lacks sufficient detail to be informative. It is not verbose, but its brevity results in under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema details, the description fails to set expectations about return format, data limits, or any other relevant context. The tool finds all entities, which could return large datasets, yet this is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no extra meaning beyond the schema's parameter descriptions. Baseline of 3 applies as per criteria for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it finds all entities of a specific type using a specific method. However, it does not differentiate from sibling tools like entity_list_entities_tool or search_search, which have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as entity_list_entities_tool or search_search. The description merely states what it does without context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search entities with Cyoda-native search conditions.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_model | Yes | The type of entity to search (e.g., 'laureate', 'subscriber', 'job') | |
| search_conditions | Yes | Cyoda search condition structure: { "type": "group", "operator": "AND" | "OR", "conditions": [ { "type": "lifecycle", "field": "state", "operatorType": "EQUALS", "value": "VALIDATED" }, { "type": "simple", "jsonPath": "$.category", "operatorType": "EQUALS" | "CONTAINS" | "GREATER_THAN" | "LESS_THAN", "value": "physics" } ] } For backward compatibility, simple field-value pairs are also supported: {"field1": "value1", "field2": "value2"} | |
| entity_version | No | The entity model version (default: from config) | 1 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully convey behavioral traits. It only says 'search', implying a read operation, but does not explicitly state that it is non-destructive, or disclose any other behaviors such as performance characteristics or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), which is efficient but may be too brief to cover essential information like behavioral traits or usage context. It is front-loaded with the key action but lacks structure for complex details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the input semantics well, but given the complexity of the search_conditions parameter and the presence of an output schema, it does not fully explain the tool's behavior, limitations, or return value structure. It is minimally adequate but incomplete for a sophisticated tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, and the description adds significant value by detailing the Cyoda-native search condition structure, including example JSON and backward compatibility notes, which goes beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it searches entities with Cyoda-native conditions, clearly indicating a search action on a specific resource. However, it does not differentiate from sibling tools like 'search_find_all' or 'entity_list_entities_tool', which also retrieve entities but with different methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, context, or scenarios where other tools (e.g., 'search_find_all') would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export entity workflows to a JSON file.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_name | Yes | Name of the entity | |
| model_version | Yes | Version of the model | |
| file_path | Yes | Path where to save the workflow file (relative to project root or absolute) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the action (export) but does not mention overwriting, error handling, permissions, or return format. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently communicates the primary action. It is front-loaded and avoids redundancy, though it could be slightly more detailed without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (covering returns), the description adequately states the purpose. However, it lacks details on file creation behavior and preconditions, making it only minimally complete for a file export tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds no additional meaning beyond the schema, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Export entity workflows to a JSON file' clearly states the verb and resource. It distinguishes from siblings like import, list, and validate, but does not specify the entity scope or output schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool over alternatives like import or list, leaving the agent uncertain about appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import entity workflows from a JSON file.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_name | Yes | Name of the entity | |
| model_version | Yes | Version of the model | |
| file_path | Yes | Path to the workflow file (relative to project root or absolute) | |
| import_mode | No | Import mode ("REPLACE" or other supported modes) | REPLACE |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks details about side effects (e.g., does it replace existing workflows?), error handling, permissions needed, or the behavior of different import modes. The word 'Import' implies mutation, but no behavioral context is added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no wasted words. While concise, it could be slightly expanded to include key context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (not shown), the description omits important context such as the consequences of the import (e.g., default mode REPLACE), file path flexibility, and what the output represents. For a tool with 4 parameters and no annotations, the description is too minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for each parameter. The description adds no additional meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Import'), the resource ('entity workflows'), and the source format ('from a JSON file'). It effectively distinguishes this tool from sibling tools like export, list, and validate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites, such as validating the file first or considering import mode options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available workflow files in the specified directory.
| Name | Required | Description | Default |
|---|---|---|---|
| base_path | No | Base directory to search for workflow files (relative to project root or absolute) | application/resources/workflow |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'List available workflow files' without specifying whether the listing is recursive, what 'available' means, permissions required, or output format. This is insufficient for an agent to infer side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential purpose without extraneous words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a simple list tool with one parameter, but it lacks details about output structure (though an output schema exists) and does not clarify if subdirectories are included. It provides minimal context beyond the basic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters, and the description mirrors the schema's mention of 'specified directory'. No additional semantics (e.g., path formats, permissions) are provided beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'workflow files', and the scope 'in the specified directory'. It effectively distinguishes from sibling tools like export, import, and validate, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing workflow files in a directory but provides no explicit guidance on when to use this tool versus alternatives (e.g., search tools) or any prerequisites. Usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a workflow file for correct JSON structure and required fields.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to the workflow file (relative to project root or absolute) |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full burden. It states validation but does not disclose side effects, error behavior, or return format, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, and front-loaded with essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimal but adequate for a simple validation tool with one parameter and an output schema; however, lacks details on output meaning and error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter 'file_path' already has a clear description. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (validate) and resource (workflow file) and specifies what is checked (JSON structure and required fields), distinguishing it from sibling tools like list or export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.7edge_message_get_edge_message_tooledge_message_send_edge_message_toolentity_create_entity_toolentity_delete_entity_toolentity_get_entity_toolentity_list_entities_toolentity_update_entity_toolsearch_find_allsearch_searchworkflow_mgmt_export_workflows_to_file_toolworkflow_mgmt_import_workflows_from_file_toolworkflow_mgmt_list_workflow_files_toolworkflow_mgmt_validate_workflow_file_toolScored across 13 tools
Most tools are clearly distinct by functional domain (edge messages, entities, workflows). The potential confusion between 'search_find_all' and 'search_search' is mitigated by their descriptions indicating different query capabilities, but an agent might still misselect.
Tool names follow inconsistent conventions: some use prefixes like 'edge_message_', 'entity_', 'workflow_mgmt_', while others use 'search_'. The naming mixes full words with abbreviations ('mgmt') and appends '_tool' inconsistently.
13 tools is a reasonable count for a server covering edge messages, entity CRUD, and workflow management. It is slightly on the higher side but not excessive.
The entity management covers CRUD and two search options, which is good. Edge messages lack delete/update. Workflow management is file-based and lacks direct lifecycle operations like create or delete, leaving notable gaps.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Let AI agents query data and act across all your business apps via MCP.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
