An MCP (Model Context Protocol) server that connects AI agents like Cursor and Claude Code to your NomaCMS project. Manage collections, fields, content entries, assets, and webhooks programmatically through natural language.
NOMA_API_KEY: API key from User settings → API keys — see API key abilities.
NOMA_PROJECT_ID: Your project's UUID — you can find it on the project home page or under Project settings → API Access
Related MCP server: elmapicms-mcp-server
Add this to your Cursor MCP settings (~/.cursor/mcp.json):
{
"mcpServers": {
"nomacms": {
"command": "npx",
"args": ["-y", "@nomacms/mcp-server"],
"env": {
"NOMA_API_KEY": "your-api-key",
"NOMA_PROJECT_ID": "your-project-uuid"
}
}
}
}Add the MCP server using the Claude Code CLI:
claude mcp add nomacms \
-e NOMA_API_KEY=your-api-key \
-e NOMA_PROJECT_ID=your-project-uuid \
-- npx -y @nomacms/mcp-serverget_project — Get project information (default_locale, locales, etc.)
add_project_locale — Add a locale code to the project (requires admin)
set_default_project_locale — Set the default locale (requires admin)
Removing locales is intentionally not exposed here (use Project settings → Localization in the NomaCMS dashboard if you must remove a locale).
list_collections — List all collections
get_collection — Get a collection with its full field schema
create_collection — Create a collection (with optional batch field creation)
update_collection — Update a collection's name and slug
reorder_collections — Reorder collections
create_field — Add a field to a collection
update_field — Update a field
reorder_fields — Reorder fields within a collection
list_entries — List entries with advanced filtering (where with 13 operators, OR groups, relation filtering), sorting, pagination, count, and first
get_entry — Get a single content entry
create_entry — Create a content entry
update_entry — Update a content entry
patch_entry — Partially update an entry (HTTP PATCH; merge only the fields you send)
publish_entry — Publish the draft as a new immutable version (update)
unpublish_entry — Clear the live published pointer; versions retained (update)
delete_entry — Soft-delete a content entry (moves to trash)
bulk_create_entries — Create multiple entries atomically
bulk_update_entries — Update multiple entries atomically by UUID
bulk_delete_entries — Delete multiple entries atomically by UUID
link_entry_translation — Link two entries (different locales) into the same translation group (POST …/link-translation; requires update ability)
list_entry_versions — List version history for an entry
get_entry_version — Fetch one version by number (includes snapshot payload)
revert_entry_version — Restore draft from a prior snapshot and publish (update)
update_entry_version_label — Edit label/description on a version; snapshot unchanged (update)
Content API shape: Each entry has uuid, locale, published_at, and fields (custom field values). Richtext values are markdown strings on write; on read they are either raw markdown or rendered HTML depending on the field’s editor.outputFormat (markdown vs html). Relation fields return nested entry objects (or arrays for one-to-many) on read; on write send only the related entry’s UUID or numeric id (never the full nested object from a previous get_entry). get_entry supports translation_locale, exclude, timestamps, and state query parameters.
Asset URLs: The API returns url, thumbnail_url, and original_url as stable links (optional ?variant=thumbnail or ?variant=original).
list_assets — List assets with pagination
get_asset — Get an asset by UUID or filename
upload_asset — Upload a file as an asset
bulk_upload_assets — Upload multiple files atomically
bulk_update_asset_metadata — Update metadata for multiple assets atomically
delete_asset — Delete an asset
list_webhooks — List all webhooks for the project
get_webhook — Get a webhook by UUID
create_webhook — Create a webhook for content and auth events (name, url, events, sources; optional description, secret, payload, status, collection_ids)
update_webhook — Update a webhook by UUID (same fields as create)
delete_webhook — Delete a webhook by UUID
list_webhook_logs — List delivery logs for a webhook (uuid; optional paginate, page)
The server exposes three reference resources that AI agents can read for context:
Field Types Reference (nomacms://field-types) — Complete reference of all 16 field types, their options, validations, and common patterns.
Collections Guide (nomacms://collections-guide) — Guide for working with collections, singletons, reserved slugs, and best practices.
Query Reference (nomacms://query-reference) — Full documentation for content queries: where filters with 13 operators, OR groups, relation filtering, sorting, pagination, and examples.
Your API key needs the appropriate abilities for the tools you want to use:
Ability | Tools |
| list/get collections, entries, assets, webhooks; webhook logs |
| create entries, upload assets, create webhooks |
| update entries, |
| delete entries, delete assets, delete webhooks |
| create/update/reorder collections and fields; add/set default project locales (MCP does not expose locale removal) |
Create the key in the NomaCMS dashboard under User settings → API keys. Copy the Project ID from the project home page or Project settings → API Access when you configure this server.
Each MCP entry connects to a single NomaCMS project. To work with multiple projects, add separate entries in your MCP config:
{
"mcpServers": {
"nomacms-blog": {
"command": "npx",
"args": ["-y", "@nomacms/mcp-server"],
"env": {
"NOMA_API_KEY": "blog-project-api-key",
"NOMA_PROJECT_ID": "blog-project-uuid"
}
},
"nomacms-store": {
"command": "npx",
"args": ["-y", "@nomacms/mcp-server"],
"env": {
"NOMA_API_KEY": "store-project-api-key",
"NOMA_PROJECT_ID": "store-project-uuid"
}
}
}
}MIT
Add a locale code (e.g. tr, es) to the project. Requires admin API ability. Codes are lowercased. Call when setting up a multilingual site before creating translated content.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | Yes | BCP 47 / short locale code, e.g. en, tr, es, de |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions the admin requirement and that codes are lowercased, but doesn't disclose potential side effects (e.g., whether adding an existing locale errors or is idempotent) or other behavioral traits.
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?
Two concise sentences, no fluff. Every word contributes: purpose, prerequisite, usage timing, and formatting 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?
For a simple single-parameter tool with no output schema, the description covers purpose, prerequisite, and usage context. It doesn't mention error handling for duplicate locales, but 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 coverage is 100% with a description already. The tool description adds value by providing examples (e.g., tr, es) and noting lowercasing, which enhances understanding 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 tool adds a locale code to a project, with specific examples (tr, es). It distinguishes itself from the sibling tool 'set_default_project_locale' by focusing on addition rather than setting default.
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?
It explicitly requires admin API ability and advises calling it when setting up a multilingual site before creating translated content. This provides good context, though it doesn't mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple content entries atomically. If one item fails, the whole request is rolled back.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of entries to create | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It mentions atomicity and rollback, which is key, but lacks other traits like error reporting, limits, or side effects.
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 covering core purpose and key behavior; concise and to the point, though could be slightly more structured.
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?
No output schema, so description should hint at return value or error handling; it only mentions rollback on failure, missing success response and error details.
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 covers 100% of parameters with detailed descriptions (e.g., items.data format), so description adds no new parameter info beyond the atomicity note, which is behavioral.
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?
Description clearly states 'Create multiple content entries atomically', which is a specific verb and resource, and distinguishes from siblings like 'create_entry' (single) and 'bulk_update_entries' (update).
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?
Description implies usage for batch creation but does not explicitly state when to use vs alternatives (e.g., single create_entry) or any prerequisites/exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple content entries atomically by UUID. If one delete fails, no entries are deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | If true, permanently delete instead of soft-delete | |
| uuids | Yes | Entry UUIDs to delete | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses atomicity and failure atomic behavior, but does not mention authorization requirements, return values, or the distinction between soft/hard delete (force parameter is not described).
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 with the action and key constraint (atomicity). Every word is essential, with no redundancy.
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, the description is incomplete. It omits behavioral traits such as whether the operation is destructive, what happens on success (e.g., return values), and does not explain the force parameter's implications.
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 all parameters. The description adds no additional parameter semantics beyond the schema, warranting the baseline score of 3.
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 uses a specific verb ('Delete') and resource ('multiple content entries') and highlights the atomicity ('atomically by UUID'), which clearly distinguishes it from sibling tools like delete_entry (single entry) and other bulk operations.
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 explains when to use this tool (for atomic bulk deletion) and the critical behavior ('If one delete fails, no entries are deleted'). It does not explicitly mention alternatives, but the context is clear given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update metadata for multiple assets atomically by UUID. If one item fails, all updates are rolled back.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of metadata updates |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral trait: atomicity with rollback on failure. No annotations provided, so description adds significant value. Lacks details on permissions or rate limits, but atomicity is well covered.
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?
Two efficient sentences: first states purpose and resource, second adds behavioral detail. No wasted words.
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?
Tool is simple (one parameter, array of objects). Atomicity and rollback are covered. No output schema, but a brief mention of expected return could improve completeness; otherwise well-specified.
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?
Input schema has 100% description coverage, so baseline is 3. Description adds 'atomically' and 'by UUID' but does not add parameter-specific details beyond what 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?
Description clearly states it updates metadata for multiple assets atomically by UUID. Distinguishes from siblings like 'update_asset' (single) and 'bulk_update_entries' (different resource).
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?
Atomicity is mentioned, suggesting use when all-or-nothing updates are needed. However, no explicit exclusions or alternative tools (e.g., 'use update_asset for single updates') are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple content entries atomically by UUID. If one item fails, all updates are rolled back. Saves never change publish state — call publish_entry per UUID to mint new versions after bulk updates.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of entries to update | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses atomic rollback and no publish state change, but lacks information on auth or rate limits which are critical for a bulk mutation tool.
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?
Two sentences, front-loaded with purpose and behavior, no extra words.
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?
Covers atomicity and publish state well, but lacks return value description; no output schema to 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?
Schema has 100% parameter description coverage, so the description adds little beyond 'by UUID' and atomically. Baseline 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 it updates multiple content entries atomically by UUID, distinguishing it from siblings like bulk_create_entries and bulk_delete_entries.
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?
Provides clear guidance on publish state and references publish_entry for versioning, but does not explicitly exclude single-entry updates or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload multiple local files as assets atomically. If one upload fails, all uploads are rolled back.
| Name | Required | Description | Default |
|---|---|---|---|
| file_paths | Yes | Absolute file paths to upload |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses critical behavior: atomicity and rollback on failure. This is valuable for an agent. However, it could be improved by mentioning any size limits, permissions required, or side effects.
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 extremely concise: two sentences, front-loaded with the verb and resource. Every sentence adds value (purpose and atomic behavior). No superfluous text.
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?
For a one-parameter tool with no output schema, the description covers the main behavioral aspect (rollback). However, it lacks details on file size limits, supported file types, and return value structure. Minor gaps prevent a perfect score.
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% for the single parameter 'file_paths' which is already described as 'Absolute file paths to upload'. The description does not add parameter-specific detail beyond the schema, but the atomicity context is relevant. Baseline 3 is appropriate due to high schema 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 the tool's purpose: 'Upload multiple local files as assets atomically.' It specifies the verb (upload), the resource (multiple local files as assets), and includes key behavior (atomicity and rollback). This distinguishes it from the sibling tool 'upload_asset' which handles single files.
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 batch uploads with atomicity, but does not explicitly state when to use this tool versus alternatives. It could provide guidance on when not to use (e.g., for single file uploads) or mention prerequisites like file size limits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new collection. Optionally include field definitions to create the collection with its full schema in a single request.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name (max 60 chars) | |
| slug | Yes | URL-friendly identifier, kebab-case (max 60 chars) | |
| fields | No | Array of field definitions to create with the collection | |
| is_singleton | No | If true, collection can only have one entry |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose key behaviors like mutability, idempotency, error handling (e.g., duplicate slug), or required permissions. It only hints at atomic schema creation.
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?
Two succinct sentences with no extraneous information. The first states the core action, the second adds the key optional behavior. 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 minimal for a creation tool with 4 parameters and no output schema. It lacks detail on return values, uniqueness constraints, and error conditions. The detailed schema compensates partly but not fully.
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% with detailed property descriptions. The description adds summary context ('optionally include field definitions') but doesn't enrich individual parameter understanding 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 action ('Create'), the resource ('a new collection'), and the optional inclusion of field definitions. This distinguishes it from siblings like 'update_collection' and 'create_field'.
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 use for creating a new collection but provides no explicit guidance on when to use alternative tools (e.g., creating fields separately) or prerequisites. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new content entry in a collection
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Object where keys are field names and values are the content (e.g. { title: 'My Post', slug: 'my-post' }). Richtext fields: use a markdown string, not Lexical/HTML objects. Relation fields: on write send the related entry's UUID string or numeric id only; one-to-one = one value, one-to-many = array of UUIDs/ids. Do not pass the nested entry object from get_entry/list_entries. Media fields: asset UUID strings and/or numeric asset ids (array when multiple). | |
| state | No | Publication state: 'published' or 'draft' (default) | |
| locale | No | Locale code (e.g. 'en') | |
| status | No | Deprecated alias for state: 'published' or 'draft' | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It simply states 'Create a new content entry' without detailing error handling, validation, return values, or any side effects. This is insufficient for a mutation tool.
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 redundant or unnecessary words, making it highly concise and front-loaded.
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 has 5 parameters, nested objects, and no output schema, the description is too brief. It lacks information about return values, validation rules, or edge cases, leaving significant gaps for the agent.
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 baseline is 3. The tool description adds no extra meaning beyond the detailed parameter descriptions already present in the input 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 ('Create'), the resource ('content entry'), and the context ('in a collection'). It effectively distinguishes this tool from siblings like 'bulk_create_entries' (bulk) and 'update_entry' (update).
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 provides no guidance on when to use this tool versus alternatives such as 'bulk_create_entries' for multiple entries or 'update_entry' for existing entries. No prerequisites or usage context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a new field to a collection
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Field identifier in kebab-case (max 60 chars) | |
| type | Yes | Field type: text, number, richtext, boolean, date, media, relation, select, longtext, group, etc. | |
| label | Yes | Display label (max 60 chars) | |
| options | No | Field-specific options (e.g. { repeatable: true } for group fields). For richtext: { editor: { type: 1, outputFormat: 'html' | 'markdown' } }. For relation: { relation: { collection: <target collection id, slug, or name>, type: 1 | 2 }, includeDraft?: boolean } (1 = one-to-one, 2 = one-to-many). | |
| description | No | Field description | |
| placeholder | No | Placeholder text | |
| validations | No | Validation rules (e.g. { required: { status: true, message: 'Required' } }) | |
| collection_slug | Yes | The slug of the collection to add the field to | |
| parent_field_id | No | Internal ID of a group field to nest this field under |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose behavioral traits such as error handling, side effects (e.g., constraint validation), or return value. The term 'Add' suggests mutation but lacks detail.
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 with no extraneous words. Efficient and to the point.
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?
For a complex tool with 9 parameters and no output schema, a one-sentence description is insufficient. It lacks context on behavior, error conditions, and return format, leaving the agent underinformed.
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 descriptions are present, so the schema already documents parameters. The description adds no additional semantic value beyond the schema, meeting the baseline.
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 'Add a new field to a collection' clearly states the verb (add) and resource (field to collection), distinguishing it from siblings like update_field or reorder_fields.
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 explicit when-to-use or alternatives are provided, but the context of creating versus updating or reordering fields is implied. Missing prerequisites like collection existence or field uniqueness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a webhook for content and auth events
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Destination URL | |
| name | Yes | Webhook display name | |
| events | Yes | Event names | |
| secret | No | Optional HMAC secret | |
| status | No | Webhook active status | |
| payload | No | Whether to include payload details | |
| sources | Yes | Event sources (e.g. cms, api) | |
| description | No | Optional description | |
| collection_ids | No | Optional collection ID filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It fails to mention side effects (e.g., immediate activation, test events), required permissions, or idempotency, leaving critical behavioral context unknown.
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 with no fluff, but it sacrifices necessary detail for brevity. It earns its place by stating purpose but fails to cover other essential aspects.
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 complexity (9 parameters, no annotations, no output schema), the description is insufficient. It does not explain webhook behavior, available events, return values, or prerequisites, making it incomplete for correct agent usage.
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?
Since schema coverage is 100%, the baseline is 3. The description adds no additional meaning to parameters beyond what the schema provides (e.g., 'Event names', 'Destination URL'). The brief mention of 'content and auth events' vaguely relates to the events parameter but does not clarify format or options.
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 'Create' and resource 'webhook', and specifies 'for content and auth events', differentiating it from siblings like delete_webhook or update_webhook. However, it could be more specific about what 'content and auth events' entail.
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 provides no guidance on when to use this tool versus alternatives (e.g., list_webhooks, update_webhook) and no prerequisites or exclusions. The agent lacks context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an asset by UUID
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The asset UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure. It implies destruction but does not explicitly state irreversibility, permissions needed, or side effects like cascading deletes.
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?
A single sentence that succinctly conveys the tool's purpose with no fluff or unnecessary words. Ideal 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?
For a simple delete tool with one parameter and no output schema, the description provides the core information. However, it lacks context on reversibility, error behavior, or permissions, which would make it more complete.
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 single parameter 'uuid' is fully described in the schema with 'The asset UUID'. Schema coverage is 100%, so baseline is 3; the description adds no additional semantic value 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 'Delete an asset by UUID' clearly states the verb (Delete) and resource (asset) along with the identifier (UUID), effectively distinguishing it from sibling tools like delete_entry or delete_webhook.
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 (e.g., bulk_delete_entries) or any prerequisites. The description only states the action without context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Soft-delete a content entry (moves to trash). Can be restored from the admin panel.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses soft-delete and restorability, which adds value beyond schema. However, lacks details on permissions, side effects, or linked data impact. With no annotations, more depth would be beneficial.
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, front-loaded with key 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?
Adequate for a simple tool with two parameters and no output schema. Covers core behavior and recovery path, but missing some potential edge cases.
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 already describes both parameters with 100% coverage; description does not add extra meaning beyond what is in 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?
Clearly states the action (soft-delete), the target (content entry), and key behavior (moves to trash, restorable). Distinguishes from other delete tools like 'delete_asset' and 'bulk_delete_entries'.
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?
Implies usage for entries that need restore capability, but does not explicitly state when to use vs alternatives like 'bulk_delete_entries' or 'delete_asset'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook by UUID
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | Webhook UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only states 'delete'. It does not disclose if deletion is irreversible, side effects, or authorization requirements, leaving 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?
Extremely concise single sentence. However, it omits important context that could be added without much length.
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?
For a simple single-parameter delete operation, the description is minimally adequate but lacks detail on return values, reversibility, or impact.
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 parameter description ('Webhook UUID') is minimal. The description adds no extra meaning beyond the schema, meeting the baseline.
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), resource (webhook), and identifier (by UUID). It distinguishes well from siblings like create_webhook and list_webhooks.
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 prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an asset by its UUID or by filename.
| Name | Required | Description | Default |
|---|---|---|---|
| by_name | No | If true, looks up by filename instead of UUID | |
| identifier | Yes | Asset UUID or filename |
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 does not disclose read-only nature, error behavior for missing assets, or any prerequisites. Only states what the tool does, not how it behaves beyond that.
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 filler. Every word adds value.
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?
For a simple get tool with 2 parameters and no output schema, the description is minimally adequate. However, it lacks details on return format, error behavior, or confirmation that it is a read-only operation, which would enhance completeness.
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 the baseline is 3. The description adds context that the tool supports two lookup modes (UUID or filename), which aligns with the 'by_name' boolean. However, it does not provide syntax or examples 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 tool retrieves a single asset by UUID or filename, distinguishing it from list_assets and delete_asset. The verb 'Get' and resource 'asset' are specific.
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 retrieving a single asset by two methods, but does not provide explicit guidance on when to use this tool versus alternatives like list_assets or search endpoints. No exclusions or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single collection with its full field schema by slug
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The collection slug (e.g. 'blog-posts') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool performs a read operation and returns the full field schema, which provides behavioral context beyond the schema's parameter description. However, it does not mention error handling, authentication, or rate limits, which would be expected for a complete behavioral profile.
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 that conveys the essential information without any redundant or extraneous content.
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?
For a simple get-by-slug tool, the description adequately covers the return content (full field schema) and the required parameter. It does not mention potential errors or prerequisites, but the combination of low parameter count and clear purpose keeps it reasonably complete.
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 provides 100% description coverage for the single parameter (slug). The tool description merely echoes 'by slug' without adding new semantic meaning, so it does not improve beyond the baseline.
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 ('Get'), the resource ('a single collection'), and the identifier ('by slug'). It also specifies the return includes the full field schema. This distinguishes it from sibling tools like list_collections and create_collection.
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 use when you need a single collection by slug, but it does not explicitly contrast with alternative tools such as list_collections for retrieving multiple collections or get_project for project-level data. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single content entry by UUID. Response includes uuid, locale, published_at, and a fields object (custom field values — not a nested data key). Relation fields appear as nested entry objects (one-to-one) or arrays of entries (one-to-many), not as bare UUIDs.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| state | No | draft or published | |
| locale | No | Locale code for the entry to load | |
| exclude | No | Comma-separated field names to exclude from `fields` (e.g. 'body,excerpt') | |
| timestamps | No | If true, include created_at and updated_at on the entry | |
| collection_slug | Yes | The collection slug | |
| translation_locale | No | If set, return the linked translation in this locale instead of the entry identified by uuid (same translation group). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully describes the response structure (uuid, locale, published_at, fields object) and clarifies critical behaviors: fields are custom and not nested under 'data', and relations are expanded into nested objects/arrays rather than bare UUIDs. This adequately informs the agent about the tool's output.
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?
Two efficient sentences front-loaded with purpose and followed by critical response details. Every sentence earns its place with no redundancy.
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 7 parameters, no output schema, and a simple read operation, the description covers core behavior and response format well. It could mention error handling or default behavior for optional params, but the existing detail is sufficient for agent usage.
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 the schema already describes all 7 parameters. The description adds marginal value beyond the schema, mainly clarifying the fields structure. It does not elaborate on parameter-specific nuances (e.g., state values, locale format).
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 ('get'), resource ('a single content entry'), and identifier ('by UUID'), distinguishing it from sibling tools like list_entries and get_entry_version.
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 fetching a single entry by UUID but does not provide explicit guidance on when to use this versus alternatives like list_entries or get_entry_version. No 'when not' or contextual exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single version's metadata and raw snapshot payload. The snapshot contains the saved field values in restoration format; for API-rendered content use get_entry with state='published'.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| version_number | Yes | The version number (1-based) | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses snapshot format as 'restoration format' but does not mention permissions, error handling, rate limits, or if the operation is read-only. Adequate for a simple fetch, but lacks detail on behaviors beyond what is stated.
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?
Two concise sentences, front-loaded with the primary purpose. Every sentence adds value with no redundancy, achieving high information density.
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 no output schema and no annotations, the description explains the snapshot format and contrasts with get_entry. It covers the core functionality well, but could mention that version_number must be valid and the return type. Still, it is fairly complete for a straightforward read 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% with descriptions for all three parameters. The description adds no additional meaning beyond the schema, so 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 'Fetch' and the resources 'single version's metadata and raw snapshot payload'. It distinguishes from sibling tool 'get_entry' by specifying alternative for rendered content, making the purpose unambiguous.
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?
Provides explicit guidance on when to use (fetching version metadata and snapshot) and when not to (for rendered content, use get_entry with state='published'). Names the alternative tool, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about the current Noma project (name, uuid, default_locale, locales, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description implies read-only behavior ('Get information'), but no explicit statement of non-destructive nature. With no annotations, the description could be more explicit about safety and idempotency.
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 with no fluff. Front-loads the action and resource, then provides examples.
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?
For a zero-parameter, simple read operation, the description is fully adequate. It covers what the tool does and hints at return fields.
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?
No parameters, so description only needs to clarify output. It adds value by listing example fields (name, uuid, etc.), which helps the agent understand what information is returned.
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?
Description clearly states it retrieves project info with specific fields listed (name, uuid, etc.). It distinguishes from sibling tools that perform mutations like add_project_locale or set_default_project_locale.
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. While it's implicitly the only read-only project tool, there is no explicit when-to or when-not-to context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a webhook by UUID
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | Webhook UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks behavioral details such as read-only status, error handling, or permission requirements. For a simple read operation, more context is expected.
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?
One sentence with no waste, though it could be slightly expanded to include return value or error cases 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?
No output schema is present, and the description does not explain what the response contains (e.g., webhook details). This is a significant gap for a minimal 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% coverage with a simple uuid parameter description. The tool description adds no extra meaning beyond the schema, so a 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 "Get a webhook by UUID" clearly states the verb and resource, and distinguishes from sibling tools like list_webhooks and update_webhook.
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 a UUID is known but provides no explicit guidance on when to use this tool versus alternatives like list_webhooks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Merge two entries in the same collection into one translation group (same as dashboard “link translation”). Both entries must exist, belong to this collection, and have different locales. There is no unlink via API — use the dashboard if you need to split a group. Requires an API key with update ability.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | UUID of the first entry (the “anchor”; both entries are merged into one translation group) | |
| collection_slug | Yes | The collection slug | |
| translation_entry_uuid | Yes | UUID of the second entry to link (must be a different locale than the first) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: merging (no unlink via API), require update API key ability, and checks that entries exist and have different locales. While it doesn't cover idempotency or rate limits, the important behavioral constraints are well communicated.
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?
Three sentences, each earning its place: first defines purpose, second adds constraints, third provides limitation and auth requirement. No redundancy, directly helpful.
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 no output schema, the description covers what the tool does (merge into translation group), prerequisites (existing entries, different locales, same collection), limitations (no unlink), and auth requirement (update ability). Sufficient for an agent to decide when and how to use.
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% (all three params described), so baseline is 3. The description adds value beyond schema: it explains the 'anchor' role of uuid, emphasizes that translation_entry_uuid must be a different locale, and clarifies that collection_slug identifies the collection. This enriches understanding.
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 'Merge two entries in the same collection into one translation group', specifying the verb (merge/link), resource (entries), and context (translation group, same collection, different locales). It distinguishes this from sibling tools like create_entry or update_entry which deal with individual entries, not linking.
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?
Explicitly states conditions: 'Both entries must exist, belong to this collection, and have different locales.' Also provides a when-not: 'There is no unlink via API — use the dashboard if you need to split a group.' This gives clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List assets in the project with optional pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| paginate | No | Items per page | |
| per_page | No | Deprecated alias for paginate |
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 states 'list assets' without confirming read-only, ordering, limits, or return structure.
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 that gets to the point. Could include more detail but no wasted words.
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?
No output schema and many sibling listing tools. Description lacks details on pagination behavior (defaults, limits), sorting, or what fields are returned, making it incomplete for an agent to use effectively.
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 covers all parameters (100% coverage), so baseline is 3. Description adds 'optional pagination' which aligns with page and paginate, but no further semantics 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?
Description clearly states 'list assets' which is a specific verb and resource. However, it does not differentiate from sibling tools like list_collections or list_entries, which also list items in the project.
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 others. Does not mention alternatives like get_asset for specific items or filtering options besides pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all collections in the project
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must convey behavioral traits. It states 'list all collections', implying a read-only operation, but does not disclose any side effects, performance notes, or output 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?
Single sentence with no wasted words. Efficient and to the point.
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?
For a simple list tool with no parameters, description covers the essential purpose. However, mentioning the return format or that it returns an array would enhance completeness.
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?
No parameters exist, and schema coverage is 100%. Description doesn't need to add param info; baseline score of 4 applies.
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?
Description clearly states it lists all collections in the project, matching the name and title. It distinguishes from siblings like 'get_collection' which fetches a single collection.
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 explicit guidance on when to use this tool over alternatives. While the name suggests it lists all collections, there is no mention of when not to use it or comparison with sibling 'get_collection'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List content entries for a collection with advanced filtering, sorting, and pagination. Use the 'where' parameter for powerful queries. Read the 'query-reference' resource for full documentation on operators and examples.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort by field:direction, comma-separated for multiple. Examples: 'created_at:desc', 'title:asc,created_at:desc'. Supports core columns (id, created_at, updated_at, published_at) and custom field names. | |
| count | No | If true, return only the count of matching entries: { count: N } | |
| first | No | If true, return only the first matching entry as a single object instead of an array | |
| limit | No | Limit the number of results (ignored if paginate is set) | |
| state | No | Filter by state: 'draft' or 'published'. Defaults to published entries. | |
| where | No | Filter conditions as a nested object. Supports operators: eq, lt, lte, gt, gte, not, like, in, not_in, null, not_null, between, not_between. Simple: { "state": "published" }. With operators: { "price": { "lt": 50 }, "title": { "like": "news" } }. OR group: { "or": [{ "tags": "clearance" }, { "campaign": { "name": "Summer" } }] }. Relation filter: outer key = relation field on this collection; inner keys = field names on the related entry, e.g. { "author": { "name": { "eq": "John" } } }. Core columns (id, uuid, locale, state, created_at, updated_at, published_at) can be filtered directly. | |
| locale | No | Filter by locale (e.g. 'en') | |
| offset | No | Skip N results (requires limit to be set) | |
| exclude | No | Comma-separated field names to exclude from response (e.g. 'content,excerpt') | |
| paginate | No | Enable pagination with N items per page. Returns paginated response with meta data. Overrides limit/offset. | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It implies read-only by listing, but does not explicitly state safety, side effects, or rate 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?
Three sentences are concise and front-loaded with purpose. No wasted words.
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?
No output schema; description lacks details on default return format, pagination structure, and edge cases. Minimal completeness for a complex tool with 11 parameters.
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 covers all parameters, so baseline is 3. The description adds some value by highlighting 'where' and pointing to reference, but does not add significant new 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 tool lists content entries for a collection with advanced features. It distinguishes from siblings like list_assets, but does not explicitly differentiate from get_entry.
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 guides use of the 'where' parameter and references external docs, but does not explain when to prefer this over alternatives like get_entry.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all published versions for a content entry (newest first). Each version is an immutable snapshot taken at publish time. Response includes version_number, label, description, published_at, created_by, and is_current_published for each version.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states versions are immutable snapshots taken at publish time, which is key behavioral context. It also lists response fields, enhancing transparency.
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?
Three efficient sentences: purpose with ordering, behavioral note, and response fields. No fluff, front-loaded with key info.
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 no output schema, the description enumerates response fields. For a simple list tool with two required parameters, it covers purpose, behavior, and output adequately.
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 is 3. The description does not add meaning beyond the schema, which already describes uuid and collection_slug adequately.
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 published versions for a content entry, ordered newest first. It uses a specific verb and resource, distinguishing it from sibling tools like get_entry_version.
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 versions but does not explicitly state when to use this tool versus alternatives like get_entry_version, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List delivery logs for a webhook
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number | |
| uuid | Yes | Webhook UUID | |
| paginate | No | Items per page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It does not disclose pagination behavior, ordering, or what constitutes a 'delivery log'. The schema reveals pagination params but the description adds no behavioral context beyond the 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?
A single sentence that is front-loaded and efficient. Could potentially add a bit more guidance (e.g., about pagination defaults) without harming 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?
With no output schema, the description should clarify return format (e.g., array of logs, pagination info). It does not, leaving the agent with incomplete context for a listing 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 description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema's scope, merely restating the tool's function.
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?
Description clearly states the action 'List' and the resource 'delivery logs for a webhook'. It distinguishes from sibling tools like list_webhooks (which lists webhooks themselves) and get_webhook (which retrieves a single webhook).
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 retrieving logs for a specific webhook via the required uuid parameter. However, it provides no explicit guidance on when to use this tool versus alternatives, or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all webhooks configured for the current project
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It only states 'list', but does not explain expected behavior such as pagination, ordering, or return format. This is lacking for a read operation.
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 is front-loaded and contains no extraneous information. Every word is necessary.
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?
For a simple list tool with no parameters, the description covers the basic scope. However, it lacks details about the output (e.g., what fields are returned) and does not mention any limits or ordering, leaving some ambiguity.
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 no parameters, so the description is not required to document them. However, it adds value by clarifying the scope ('current project'), earning a score above baseline 3.
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 ('List') and the resource ('webhooks'), specifying the scope ('configured for the current project'). This distinguishes it from siblings like 'get_webhook' (single) and 'list_webhook_logs' (different resource).
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 viewing all webhooks but provides no explicit guidance on when to use versus alternatives (e.g., 'get_webhook' for details). No context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a content entry (HTTP PATCH). Only include fields you want to change (e.g. relations, one field). Saves NEVER change the publish state — call publish_entry explicitly to mint a new version. Prefer this over update_entry when you are not replacing the entire entry.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Fields to merge; omit unchanged fields. Richtext values are markdown strings. Relation fields: on write send the related entry's UUID string or numeric id only; one-to-one = one value, one-to-many = array of UUIDs/ids. Do not pass the nested entry object from get_entry/list_entries. Media fields: asset UUID strings and/or numeric asset ids (array when multiple). | |
| uuid | Yes | The entry UUID | |
| locale | No | Locale code | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that it uses PATCH method, that publish state is unchanged, and provides detailed format for richtext, relations, and media fields. Lacks mention of auth requirements, rate limits, or conflict handling, but overall strong for the non-annotated case.
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?
Two main sentences plus a detailed parameter block. Front-loaded with action and key behavioral warning (publish state). The parameter description is thorough but not overly verbose. Minor room for more structured presentation, but effective.
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 complexity (nested objects, no output schema), the description explains input well but does not describe what the API returns (e.g., updated entry or confirmation). With no output schema, some return value context would improve completeness.
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% but description adds significant value: explains merge semantics (include only changing fields), richtext as markdown, relation format (UUID/id, one-to-one vs one-to-many), and media asset format. This goes well beyond the schema's basic field types.
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?
Description clearly states verb 'Partially update a content entry' and identifies it as HTTP PATCH. It distinguishes from update_entry by specifying partial vs full replacement. The resource (content entry) and scope are unambiguous.
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?
Explicitly recommends preferring this over update_entry when not replacing the entire entry. Clearly states that saves do not change publish state and that publish_entry should be called separately. Provides concrete context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mint a new immutable version from the entry's current draft and make it the live published version. After this call, state=published reads from the public API will return the new snapshot and is_draft_dirty is reset to false.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explicitly states side effects: new snapshot becomes live, is_draft_dirty resets to false, and public API returns new state. Mentions immutability, which is helpful.
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?
Two sentences, no wasted words. Front-loaded with key action and outcome. Highly concise.
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?
No output schema, but description explains post-call behavior (public API update, is_draft_dirty reset). Covers what changes and the result sufficiently for a publish 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?
Schema coverage is 100%, so baseline is 3. Description does not add parameter-specific details beyond schema; it only mentions 'current draft' but no additional context for uuid or collection_slug.
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?
Description clearly states the action: minting an immutable version from the draft and making it live. It distinguishes from sibling tools like unpublish_entry and revert_entry_version by specifying 'publish' and 'live published version'.
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?
Usage is implied (when wanting to publish the current draft) but no explicit alternatives or when-not-to-use guidance is provided. No mention of prerequisites or contrasts with similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the display order of collections
| Name | Required | Description | Default |
|---|---|---|---|
| collections | Yes | Array of { uuid, order } objects |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits such as whether the operation is destructive, reversible, or has side effects on other resources.
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 with no wasted words. It is appropriately sized for a simple operation and front-loads the essential information.
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?
While the tool is simple, the description lacks context such as that collections belong to a project or that the order is relative. With sibling tools like 'update_collection', additional clarity would be beneficial.
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 the schema fully defines the parameter. The description adds no extra meaning beyond what is already in the schema, warranting a baseline score of 3.
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 the display order of collections' uses a specific verb and resource, clearly indicating the tool's purpose. It distinguishes from sibling tools like 'reorder_fields' which reorder fields, not collections.
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 'update_collection' or 'reorder_fields'. There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the display order of fields within a collection
| Name | Required | Description | Default |
|---|---|---|---|
| fields | Yes | Array of { uuid, order } objects | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden but only states it's a mutation. It does not disclose side effects (e.g., whether ordering is atomic, overwrites or appends), permissions, or error conditions.
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 with no unnecessary words, efficiently conveying 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 that there are no annotations or output schema, the description should provide more context about return values, error handling, or limitations. It only states the basic action, making it insufficient for complete understanding.
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?
Both parameters are well-documented in the schema (100% coverage), and the description adds no additional meaning beyond what the schema provides, earning the baseline score of 3.
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 ('Update') and the target ('display order of fields within a collection'), distinguishing it from sibling tools like 'reorder_collections' or 'update_field'.
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 conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restore the draft to a previous version's snapshot and publish it as a new version. The current unpublished draft is replaced. Returns the new version number.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| version_number | Yes | The version number to revert to (the snapshot to restore) | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses key behaviors: replaces current unpublished draft, publishes as new version, returns new version number. However, it omits side effects like overwriting drafts and does not mention permissions or error conditions.
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?
Two sentences, front-loaded with the main action. No unnecessary words.
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?
Covers purpose, action, and return value. Lacks mention of error handling, prerequisites (e.g., existing unpublished draft), and potential side effects, but overall adequate for a revert operation.
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% with clear descriptions for uuid, version_number, and collection_slug. The tool description adds minimal extra context beyond 'previous version's snapshot'.
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?
Description uses specific verb 'revert' and clearly states the action: restore draft to a previous version's snapshot and publish as new version. It distinguishes from siblings like get_entry_version (read-only) and publish_entry (publish current version).
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?
Description implies usage for reverting to a previous version but does not explicitly state when to use versus alternatives like get_entry_version or update_entry. No guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the project's default locale. Adds the locale to the list if it was missing. Requires admin API ability.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | Yes | Locale code to use as default (e.g. en) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey all behavioral traits. It states that the tool 'Adds the locale to the list if it was missing', which is a clear side effect. It also notes the admin requirement. However, it does not detail other behaviors like whether the operation is reversible or what happens to existing data. Adequate but not comprehensive.
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 two sentences long with no wasted words. The first sentence states the primary action, and the second provides additional behavior and a requirement. It is front-loaded and 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?
Given the tool's simplicity (single parameter, no output schema), the description covers the purpose, a key behavioral side effect, and a permission requirement. It is complete enough for an agent to understand when and how to invoke it correctly.
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 schema already provides a description for the only parameter 'locale' with an example. Schema description coverage is 100%, so baseline is 3. The tool description adds context that the locale will be added to the list if missing, which is more about behavior than parameter semantics. No additional constraints, formats, or use cases are given 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 verb 'Set' and the resource 'project's default locale'. It distinguishes itself from the sibling 'add_project_locale' by implying that this both sets as default and adds if missing, whereas the sibling likely just adds without setting as default.
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 mentions 'Requires admin API ability', which provides a precondition for use. However, it does not explicitly state when not to use this tool (e.g., when only adding a locale without setting as default) nor does it name the alternative 'add_project_locale'. Usage is implied but not fully guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear the live published pointer for an entry. The entry becomes invisible under state=published in the public API, but all historical versions are retained and still accessible via list_entry_versions / get_entry_version.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides key behavioral details: the entry becomes invisible under state=published, historical versions are retained. It does not cover permissions or rate limits, but sufficiently conveys the core behavior.
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?
Two concise sentences: the first states the action, the second explains the effects. No unnecessary words, information is front-loaded.
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?
For a simple two-parameter tool with no output schema, the description fully covers what the tool does and its consequences. No missing information.
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 both parameters are described in the schema. The description adds no extra meaning beyond the schema-provided 'The entry UUID' and 'The collection slug', so baseline score applies.
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's purpose: 'Clear the live published pointer for an entry.' It specifies the effect (invisible under state=published) and differentiates from siblings like publish_entry and list_entry_versions.
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 when to use (to unpublish) and notes that historical versions remain accessible via other tools. It doesn't explicitly state when not to use, but the context is clear for a simple unpublish action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the name and slug of an existing collection
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | New display name | |
| slug | Yes | Current slug of the collection to update | |
| new_slug | Yes | New slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only says 'update', which implies mutation. It does not disclose side effects, required permissions, idempotency, or return behavior.
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 with no unnecessary words, efficiently conveying the core functionality with zero fluff.
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 absence of output schema and annotations, the description is insufficient. It does not explain return values, prerequisites (e.g., collection existence), or uniqueness constraints for new_slug, leaving gaps for agent decision-making.
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% with descriptions for all three parameters. The description reiterates 'name and slug' but adds no additional meaning beyond the schema, so baseline score of 3 applies.
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 ('update') and the specific fields impacted (name and slug) on an existing collection, distinguishing it from create_collection and get_collection.
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 like create_collection or reorder_collections. The description does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace an existing content entry (HTTP PUT). Sends the full data payload; required fields (e.g. title, slug) must be included. Saves NEVER change the publish state — if the entry has a published version, the public API keeps serving that snapshot under state=published until you explicitly call publish_entry. Use patch_entry for partial updates and publish_entry/unpublish_entry to control visibility.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Object with field names and their new values; richtext fields are markdown strings. Relation fields: on write send the related entry's UUID string or numeric id only; one-to-one = one value, one-to-many = array of UUIDs/ids. Do not pass the nested entry object from get_entry/list_entries. Media fields: asset UUID strings and/or numeric asset ids (array when multiple). | |
| uuid | Yes | The entry UUID | |
| locale | No | Locale code | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description fully discloses key behaviors: PUT semantics, full payload requirement, no publish state change, and the public API continues serving the published snapshot. Also explains how to format relation and media fields.
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?
Description is concise: core action in first sentence, then critical behavioral notes and sibling differentiation. No unnecessary words.
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 no output schema, the description covers all necessary aspects: usage, behavioral traits, parameter details, and sibling differentiation. Complete for a mutation 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% with descriptions for all parameters. The description adds valuable context beyond schema, especially for the 'data' parameter (richtext, relation, media field handling), increasing understanding.
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?
States 'Replace an existing content entry (HTTP PUT)' clearly identifying verb and resource. Distinguishes from siblings by naming patch_entry and publish_entry/unpublish_entry.
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?
Explicitly says use for full replacement, contrasts with patch_entry for partial updates, and clarifies that saves do not affect publish state, requiring explicit publish/unpublish calls. Also notes required fields must be included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a version's editable label and/or description. The snapshot payload itself is immutable.
| Name | Required | Description | Default |
|---|---|---|---|
| uuid | Yes | The entry UUID | |
| label | No | Human-friendly label for this version (null clears it) | |
| description | No | Longer note for this version (null clears it) | |
| version_number | Yes | The version number | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses that only label/description are editable and snapshot is immutable, but doesn't mention permissions or error handling. Adequate but not thorough.
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?
Two concise sentences with no fluff. Front-loaded with key action and constraints.
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, complete schema coverage, and no output schema needed, the description provides sufficient context including the immutability of the snapshot.
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 description adds no extra parameter details beyond what the schema already provides. 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 tool updates a version's editable label and/or description, and distinguishes from siblings like revert_entry_version by noting snapshot immutability.
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 when to use it (to change label/description without affecting snapshot), but does not explicitly mention when not to use or provide alternatives. Adequate for a simple update tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing field on a collection
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Field identifier in kebab-case | |
| type | Yes | Field type | |
| label | Yes | Display label | |
| options | No | Field-specific options. For richtext: { editor: { type: 1, outputFormat: 'html' | 'markdown' } }. For relation: { relation: { collection, type: 1 | 2 }, includeDraft?: boolean }. | |
| field_uuid | Yes | The UUID of the field to update | |
| description | No | Field description | |
| placeholder | No | Placeholder text | |
| validations | No | Validation rules | |
| collection_slug | Yes | The collection slug |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only says 'Update an existing field'. It fails to disclose side effects, permissions, reversibility, or error behavior. Insufficient for a mutation tool.
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 does not earn its place by adding value beyond the tool name. It is not verbose but could include more useful information without bloat.
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 complexity of 9 parameters including nested objects, the description is far too minimal. It lacks behavioral context, return value information, and usage examples, making it incomplete for effective tool selection and invocation.
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 all parameters have descriptions, so baseline is 3. The description adds no additional meaning beyond the schema, which is acceptable but not enhanced.
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 specific verb 'update' and the resource 'field on a collection', which distinguishes it from sibling tools like create_field or reorder_fields.
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 provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It lacks context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a webhook by UUID
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Destination URL | |
| name | Yes | Webhook display name | |
| uuid | Yes | Webhook UUID | |
| events | Yes | Event names | |
| secret | No | Optional HMAC secret | |
| status | No | Webhook active status | |
| payload | No | Whether to include payload details | |
| sources | Yes | Event sources (e.g. cms, api) | |
| description | No | Optional description | |
| collection_ids | No | Optional collection ID filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only states the mutation action without disclosing side effects, authorization needs, idempotency, or error behavior. For a tool with 10 parameters, this is insufficient.
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 immediately conveys the essential action. It is front-loaded and contains no filler, though it sacrifices some detail for brevity.
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, 5 required, no output schema, and no annotations, the description is incomplete. It fails to explain the return value, error conditions, or any constraints beyond what the schema provides. An agent would lack sufficient context to use the tool confidently.
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, so the schema already explains each parameter. The tool description adds nothing beyond that. Baseline 3 is appropriate as no extra value is provided.
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 (update) and resource (webhook) with the identifier method (by UUID). It distinguishes the tool from siblings like create_webhook and delete_webhook, but could be more specific about the scope of updates (e.g., which fields).
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 provides no guidance on when to use this tool versus alternatives like patch_entry or other webhook operations. No prerequisites, use cases, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local file as an asset. Provide the absolute file path.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the file to upload |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states the action; lacks details on success/error behavior, file size limits, or authorization needs.
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?
Two concise sentences, front-loaded with purpose. No unnecessary words.
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?
For a simple tool with one parameter and no output schema or annotations, the description is minimal but functional. Could mention default behavior or return info.
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 parameter description is adequate. Description adds no further meaning beyond the schema's parameter description.
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 (upload) and the resource (local file as asset). It distinguishes from bulk upload siblings by specifying a single file and requiring absolute path.
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 like bulk_upload_assets. No prerequisites or scenarios are 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. Dates show when Glama detected each change.
v1.2.1add_project_localebulk_create_entriesbulk_delete_entriesbulk_update_asset_metadatabulk_update_entriesbulk_upload_assetscreate_collectioncreate_entrycreate_fieldcreate_webhookdelete_assetdelete_entrydelete_webhookget_assetget_collectionget_entryget_entry_versionget_projectget_webhooklink_entry_translationlist_assetslist_collectionslist_entrieslist_entry_versionslist_webhook_logslist_webhookspatch_entrypublish_entryreorder_collectionsreorder_fieldsrevert_entry_versionset_default_project_localeunpublish_entryupdate_collectionupdate_entryupdate_entry_version_labelupdate_fieldupdate_webhookupload_assetEach tool targets a distinct operation or resource. Bulk and single operations are clearly separated, and actions like publish, unpublish, patch, and update are well-differentiated through descriptions.
The naming follows a consistent verb_noun pattern in snake_case, with minor exceptions like 'link_entry_translation' and 'reorder_collections' that break the pattern slightly.
At 39 tools, the server is overpopulated for a typical CMS MCP server. While the domain is broad, many tools could be consolidated (e.g., bulk operations as parameters).
The tool surface covers most CRUD operations for entries, assets, collections, fields, and webhooks, but lacks delete operations for collections and fields, and asset file update is missing.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Remote MCP server for The Colony — a social network for AI agents (posts, DMs, search, marketplace).
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/NomaCMS/nomacms-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
