Skip to main content
Glama
kinmeic

Memos MCP Server

by kinmeic

Memos MCP Server

A Model Context Protocol (MCP) server for interacting with Memos API.

Features

  • Create Memos: Create new memos with Markdown content

  • List Memos: List memos with pagination, sorting, and CEL filter support

  • Get Memo: Retrieve a specific memo by ID

  • Update Memo: Update existing memo content and metadata

  • Delete Memo: Delete memos

  • Memo Attachments: List and set memo attachments

  • Attachment Service: Create, list, get, update, and delete individual attachments

Related MCP server: memopaper-mcp

Installation

  1. Clone this repository or download the files

  2. Install dependencies:

npm install
  1. Build the project:

npm run build
  1. Set up environment variables:

export MEMOS_BASE_URL="https://your-memos-instance.com"
export MEMOS_API_KEY="your-api-token"

For Memos API key, go to your Memos instance -> Settings -> API to generate a token.

Configuration

The server uses the following environment variables:

Variable

Required

Default

Description

MEMOS_BASE_URL

No

https://demo.usememos.com

Your Memos instance base URL

MEMOS_API_KEY

No

(empty)

Your Memos API access token

Usage

Running the Server

npm start

Or for development with auto-reload:

npm run dev

MCP Tools

The server provides the following tools:

create_memo

Create a new memo.

Parameters:

  • content (required): The memo content in Markdown format

  • visibility (optional): Visibility level - PRIVATE, PROTECTED, or PUBLIC (default: PRIVATE)

  • state (optional): Memo state - NORMAL or ARCHIVED (default: NORMAL)

  • pinned (optional): Whether to pin the memo (default: false)

Example:

{
  "content": "# My First Memo\n\nThis is a **markdown** memo.",
  "visibility": "PRIVATE",
  "pinned": false
}

list_memos

List memos with pagination, sorting, and CEL filter support.

Parameters:

  • pageSize (optional): Maximum number of memos to return (default: 50, max: 1000)

  • pageToken (optional): Page token from previous response for pagination

  • state (optional): Filter by state - NORMAL or ARCHIVED (default: NORMAL)

  • orderBy (optional): Sort order (default: display_time desc). Supports: pinned, display_time, create_time, update_time, name

  • filter (optional): CEL expression for advanced filtering (e.g., visibility == 'PUBLIC')

  • show_deleted (optional): Include deleted memos (default: false)

Examples:

// Basic list
{
  "pageSize": 50,
  "state": "NORMAL"
}

// With CEL filter
{
  "filter": "visibility == 'PUBLIC' && content.contains('meeting')",
  "orderBy": "pinned desc, display_time desc"
}

// Pagination
{
  "pageSize": 50,
  "pageToken": "eyJwYWdlU2l6ZSI6IDUwfQ=="
}

get_memo

Get a specific memo by ID.

Parameters:

  • memoId (required): The memo ID (e.g., 123 or memos/123)

update_memo

Update an existing memo.

Parameters:

  • memoId (required): The memo ID to update

  • content (optional): New content for the memo

  • visibility (optional): New visibility setting

  • state (optional): New state setting

  • pinned (optional): New pinned state

delete_memo

Delete a memo.

Parameters:

  • memoId (required): The memo ID to delete

list_memo_attachments

List all attachments for a specific memo.

Parameters:

  • memoId (required): The memo ID (e.g., 123 or memos/123)

  • pageSize (optional): Maximum number of attachments to return (default: 50, max: 1000)

  • pageToken (optional): Page token for pagination

Example:

{
  "memoId": "123",
  "pageSize": 100
}

set_memo_attachments

Set attachments for a memo (replaces all existing attachments).

Parameters:

  • memoId (required): The memo ID

  • attachments (required): List of attachment objects (use camelCase for attachment fields)

    • filename (required): The filename

    • type (required): MIME type (e.g., image/png, application/pdf)

    • content (optional): Base64 encoded file content

    • externalLink (optional): External URL (camelCase)

Note: Use content OR externalLink, not both. Do NOT include size or createTime (these are server-generated).

Important: Attachment fields must use camelCase (externalLink, not external_link) as they match the API specification.

Example:

{
  "memoId": "123",
  "attachments": [
    {
      "filename": "document.pdf",
      "type": "application/pdf",
      "externalLink": "https://example.com/doc.pdf"
    },
    {
      "filename": "small-image.png",
      "type": "image/png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
    }
  ]
}

create_attachment

Create a new attachment (can be linked to memos later).

Parameters:

  • filename (required): The filename

  • type (required): MIME type (e.g., image/png, application/pdf)

  • attachment_id (optional): Custom attachment ID

  • external_link (optional): External URL

  • memo (optional): Related memo resource name (format: memos/{memo})

Example:

{
  "filename": "document.pdf",
  "type": "application/pdf",
  "external_link": "https://example.com/doc.pdf",
  "memo": "memos/123"
}

get_attachment

Get a specific attachment by ID.

Parameters:

  • attachment_id (required): The attachment ID (e.g., 123 or attachments/123)

list_attachments

List all attachments with pagination, filtering, and sorting.

Parameters:

  • page_size (optional): Maximum number of attachments to return (default: 50, max: 1000)

  • page_token (optional): Page token for pagination

  • filter (optional): CEL expression for filtering

  • order_by (optional): Sort order (e.g., create_time desc, filename asc)

Examples:

// Basic list
{
  "page_size": 100
}

// With CEL filter
{
  "filter": "mime_type==\"image/png\"",
  "orderBy": "create_time desc"
}

// Filter by memo
{
  "filter": "memo==\"memos/123\""
}

update_attachment

Update an existing attachment.

Parameters:

  • attachment_id (required): The attachment ID to update

  • update_mask (required): Comma-separated list of fields to update (e.g., filename,type,externalLink)

  • filename (optional): New filename

  • type (optional): New MIME type

  • external_link (optional): New external URL

  • memo (optional): New related memo resource name

Example:

{
  "attachmentId": "123"",
  "update_mask": "filename,externalLink",
  "filename": "updated-name.pdf",
  "external_link": "https://example.com/new-url.pdf"
}

delete_attachment

Delete an attachment by ID.

Parameters:

  • attachment_id (required): The attachment ID to delete

MCP Resources

The server provides the following resources:

  • memos://memos: All memos from your Memos instance

  • memos://config: Current server configuration

Claude Desktop Integration

To use this server with Claude Desktop, add it to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "memos": {
      "command": "node",
      "args": ["/path/to/memos-mcp/dist/index.js"],
      "env": {
        "MEMOS_BASE_URL": "https://your-memos-instance.com",
        "MEMOS_API_KEY": "your-api-token"
      }
    }
  }
}

Development

Project Structure

memos-mcp/
├── package.json           # Node.js project configuration
├── tsconfig.json          # TypeScript configuration
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server definition
│   ├── memos-client.ts    # Memos API client
│   ├── types.ts           # TypeScript type definitions
│   └── tools/
│       ├── memo-tools.ts      # Memo-related tools
│       └── attachment-tools.ts # Attachment-related tools
└── dist/                  # Compiled JavaScript output

License

MIT License

References

Available Tools

12 tools
create_attachmentB

Create a new attachment (can be linked to memos later)

ParametersJSON Schema
NameRequiredDescriptionDefault
memoNoRelated memo resource name (format: memos/{memo})
typeYesMIME type (e.g., "image/png", "application/pdf")
contentNoBase64 encoded file content
filenameYesThe filename
externalLinkNoExternal URL

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only discloses that the operation creates an attachment and that linking can happen later; it does not mention side effects, how content or externalLink are handled, or constraints on the request. For a mutating tool, this is thin.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one efficient sentence that front-loads the core action and adds a useful scoping qualifier. There is no filler, repetition, or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations, no output schema, and a five-parameter input, the description is too sparse to be fully actionable. It omits practical context such as whether content and externalLink are mutually exclusive, what happens after creation, and how this relates to the broader attachment lifecycle. It is minimally viable but leaves significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents all five parameters and their meanings. The description adds only indirect context that the memo link is not required at creation time, which is a minor supplement rather than substantial new parameter guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action and resource: 'Create a new attachment'. The parenthetical '(can be linked to memos later)' also distinguishes it from memo-linking operations like set_memo_attachments, so an agent can tell what this tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'can be linked to memos later' implies this tool is for creating an attachment before associating it with a memo, but it does not explicitly say when to use this over create_memo, set_memo_attachments, or update_attachment. No alternatives are named, so usage guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_memoB

Create a new memo

ParametersJSON Schema
NameRequiredDescriptionDefault
stateNoMemo state: NORMAL or ARCHIVED
pinnedNoWhether to pin the memo
contentYesThe memo content in Markdown format
visibilityNoVisibility level: PRIVATE, PROTECTED, or PUBLIC

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full responsibility for behavioral disclosure. It only states 'Create a new memo' and does not reveal side effects, return behavior, permission requirements, or how optional fields like visibility or pinning affect the created memo.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no filler or redundant information. It states the essential purpose immediately and is appropriately sized for a simple create operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The schema documents all parameters, and the operation is conceptually simple, but there are no annotations and no output schema. The description does not mention what the tool returns or whether creation can fail, leaving some contextual ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already documented in the schema. The description itself adds no parameter-level meaning, which matches the baseline of 3 for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Create a new memo'. This clearly distinguishes it from sibling tools like update_memo, delete_memo, and create_attachment by action and resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided for when to use this tool versus alternatives. There are no exclusions, prerequisites, or comparisons to sibling tools, leaving the usage context entirely implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_attachmentA

Delete an attachment by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
attachment_idYesThe attachment ID to delete

TDQS

A3.5/5.0
Behavior2/5

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 conveys the destructive nature via 'Delete', but does not disclose irreversibility, error behavior for non-existent IDs, cascading effects, or authentication requirements. For a mutation tool with zero annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with zero wasted words. It states the action, target, and scope efficiently, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter deletion tool, the description covers the essential purpose and parameter adequately. However, with no output schema and no behavioral notes, an agent cannot predict the response format or error handling, which leaves some gaps for a complete call workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter attachment_id is already fully documented ('The attachment ID to delete'). The description adds nothing beyond the schema, which matches the baseline of 3 when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is specific and unambiguous: 'Delete an attachment by ID' clearly names the verb (delete), the resource (attachment), and the key identifier (ID). It distinguishes itself from siblings like get_attachment, update_attachment, and create_attachment without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The usage context is implied by the name and description: use this when you need to delete an attachment. However, it does not explicitly state when not to use it or mention alternatives such as delete_memo for deleting a memo, leaving some inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_memoC

Delete a memo

ParametersJSON Schema
NameRequiredDescriptionDefault
memoIdYesThe memo ID to delete

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It only states 'delete,' implying a destructive mutation, but does not mention permanence, cascade effects on attachments, permissions, or possible errors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with no filler. It front-loads the action and resource in three words, though it sacrifices completeness for brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter delete operation with full schema coverage, the description is minimally adequate. However, as a destructive tool with no annotations, it lacks important context about side effects, reversibility, and behavior when the memo is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes memoId with 100% coverage, so the baseline applies. The description adds no additional meaning beyond the schema; it does not elaborate on how to obtain the memo ID or any special format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete) and resource (memo), which is unambiguous. It distinguishes from sibling delete_attachment by naming the memo resource, though it does not explicitly contrast with all siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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, prerequisites, or conditions such as whether the memo must exist or have no attachments. There are no exclusions or alternative routing hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_attachmentB

Get a specific attachment by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
attachment_idYesThe attachment ID (e.g., "123" or "attachments/123")

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description bears the full burden, but it only states that a specific attachment is retrieved. It does not disclose behavior such as return format, error handling, authorization needs, or whether this is strictly read-only beyond the verb 'get'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence conveys the essential operation with no filler. Every word is informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and the schema covers the parameter, but there is no output schema and the description does not clarify what is returned (binary content, metadata, or both). For an agent invoking the tool, this is a meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes the single parameter including example formats ('123' or 'attachments/123'), so the schema does the heavy lifting. The description adds little beyond restating that lookup is by ID, which matches the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Get') and resource ('attachment'), and the qualifier 'specific ... by ID' distinguishes this from sibling list_attachments. An agent can immediately tell that this tool fetches one attachment rather than enumerating them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to choose get_attachment over get_memo or list_attachments, and no exclusions or prerequisites are stated. The only usage signal is the implicit need for an attachment ID.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_memoB

Get a specific memo by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
memoIdYesThe memo ID (e.g., "123" or "memos/123")

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the action. It does not mention not-found behavior, permissions, or whether the full memo object is returned, which are relevant for a retrieval tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read operation with a well-documented ID format, the description plus schema is adequate for calling the tool. However, the lack of an output schema and any note on errors means an agent still has some uncertainty about the result and failure behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents memoId at 100% coverage, including accepted example formats, so the baseline applies. The description adds no parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a clear verb ('Get') and resource ('a specific memo by ID'), which distinguishes it from list/create/update/delete siblings at a glance. It does not explicitly mention sibling alternatives, so it stops short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus list_memos or other siblings. The description only states the operation, leaving the agent to infer selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_attachmentsA

List all attachments with pagination, filtering, and sorting

ParametersJSON Schema
NameRequiredDescriptionDefault
filterNoCEL expression for filtering
order_byNoSort order (e.g., "create_time desc", "filename asc")
page_sizeNoMaximum number of attachments to return (default: 50, max: 1000)
page_tokenNoPage token for pagination

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description alone must disclose behavior. It does state that the call supports pagination, filtering, and sorting, which are useful behavioral traits. However, it does not describe the response shape, whether a page token is returned for continuation, or any read-only guarantees, leaving some behavior to inference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly written sentence with every word earning its place. It front-loads the core purpose and the supported capabilities, with no redundant or filler content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list operation with fully documented parameters, the description is minimally viable. However, the absence of an output schema and any explicit differentiation from 'list_memo_attachments' leaves some contextual gaps about the exact scope and returned data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% parameter documentation, so the baseline is 3. The description's mention of pagination, filtering, and sorting maps to the schema parameters but adds no new semantic detail beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

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 ('all attachments') with three concrete capabilities: pagination, filtering, and sorting. The phrase 'all attachments' also helps distinguish it from the sibling 'list_memo_attachments', which is presumably scoped to a specific memo.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance about when to use this tool versus its siblings. In particular, it does not tell the agent when to use 'list_memo_attachments' instead, which is a meaningful ambiguity given the sibling list. Any differentiation is only implied by the word 'all'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_memo_attachmentsA

List all attachments for a specific memo

ParametersJSON Schema
NameRequiredDescriptionDefault
memoIdYesThe memo ID (e.g., "123" or "memos/123")
pageSizeNoMaximum number of attachments to return (default: 50, max: 1000)
pageTokenNoPage token for pagination

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description itself indicates a read-only list operation, which is adequate. However, it does not disclose that results are paginated despite pageSize/pageToken parameters, and 'all' is potentially misleading given the default/page limits. The behavior is not contradicted, but the description could do more.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no filler. The resource and scope are front-loaded, and every word contributes to identifying what the tool does.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter list tool, the schema covers parameters, but the description omits the output shape and contradicts the pagination behavior by saying 'all'. Without an output schema or annotations, an agent gets basic callability but not full expected behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 no parameter-specific meaning beyond the schema; memoId, pageSize, and pageToken are already documented. It does not explain how they interact with the listing behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear action and scope: 'List all attachments' for a targeted 'specific memo'. The phrase 'for a specific memo' differentiates it from the sibling list_attachments and get_attachment, so an agent can identify the intended resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to choose this tool over list_attachments, get_attachment, or set_memo_attachments. There are no explicit when-to-use or exclusions; usage is only implied by the tool name and the memoId parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_memosA

List memos with pagination, sorting, and CEL filter support

ParametersJSON Schema
NameRequiredDescriptionDefault
stateNoFilter by state: NORMAL or ARCHIVED
filterNoCEL expression for advanced filtering (e.g., "visibility == 'PUBLIC'")
orderByNoSort order (e.g., "pinned desc, display_time desc"). Supports: pinned, display_time, create_time, update_time, name
pageSizeNoMaximum number of memos to return (default: 50, max: 1000)
pageTokenNoPage token from previous response for pagination
showDeletedNoInclude deleted memos

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool supports pagination, sorting, and CEL filtering, but it omits defaults (e.g., whether archived or deleted memos are included by default, default sort order) and never explicitly states the operation is a read-only query. These are clear gaps for a list operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single 10-word sentence that front-loads the verb and resource; every word earns its place. Given that the schema carries the parameter detail, this brevity is appropriate and not under-specification.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter list tool with zero annotations and no output schema, the description is thin: it does not indicate what the response contains (memo list, next page token) or default filtering behavior. The rich schema covers parameters, but an agent is left to infer response shape and defaults.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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; each of the 6 parameters is already documented in detail. The description's mention of pagination/sorting/filtering adds a helpful conceptual mapping to pageToken/pageSize, orderBy, and filter, but no new parameter meaning beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List'), the resource ('memos'), and three distinctive capabilities (pagination, sorting, CEL filtering). These capabilities, plus the contrasting sibling names (create/get/update/delete), make it easy for an agent to distinguish this from get_memo and from the attachment-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit when-to-use guidance, exclusions, or named alternatives. Usage is only implied: it is the listing/query operation, contrastable with the single-record get_memo and the mutation tools. An agent must infer when to prefer this over get_memo or list_memo_attachments.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_memo_attachmentsB

Set attachments for a memo (replaces all existing attachments)

ParametersJSON Schema
NameRequiredDescriptionDefault
memoIdYesThe memo ID
attachmentsYesList of attachment objects

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden. It does surface the single most important trait — that all existing attachments are replaced — which is the destructive/mutating behavior an agent must know. However, it does not disclose side effects on replaced attachment objects (deleted vs. orphaned), permissions required, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single 10-word sentence with the core operation front-loaded and the distinguishing caveat in a tight parenthetical. Every word earns its place; no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity tool (2 simple params, no output schema), essential purpose and behavior are covered. Gaps remain: the structure of 'attachment objects' is undefined, return values are not described, and there is no indication of whether providing an empty array clears all attachments. Adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 with the schema doing the heavy lifting. The description adds no parameter-level detail; notably, it does not clarify whether the 'attachments' array expects IDs, full attachment objects, or URLs, which is a genuine ambiguity the schema also fails to resolve.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (set attachments for a memo) with an explicit resource, and the parenthetical '(replaces all existing attachments)' adds the critical scope distinction that separates this from create_attachment and update_attachment. The verb 'set' is slightly generic, but the replacement context makes 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.

Usage Guidelines2/5

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 versus alternatives. The replacement wording implies this is for overwriting the full attachment set rather than appending, but it never names create_attachment as the alternative for additive operations or states a selection condition. An agent must infer usage from the parenthetical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_attachmentC

Update an existing attachment

ParametersJSON Schema
NameRequiredDescriptionDefault
memoNoNew related memo resource name
typeNoNew MIME type
filenameNoNew filename
update_maskYesComma-separated list of fields to update (e.g., "filename,type,externalLink")
attachment_idYesThe attachment ID to update
external_linkNoNew external URL

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. 'Update' signals mutation, but the description does not disclose partial-update semantics, field validation behavior, or side effects. The required update_mask is a key behavior that is only discoverable in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with zero fluff, earning the high end for conciseness. It is somewhat under-structured, lacking context that would help an agent, but it is not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with six parameters, no annotations, and no output schema, the description is too minimal. It provides no information about update behavior, required fields beyond the schema, or consequences of the update, leaving the agent to infer everything from parameter names.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 six parameters. The description adds no additional meaning about parameter relationships, defaults, or field constraints, establishing the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Update an existing attachment' uses a clear verb-resource pair and distinguishes the tool from create/get/list/delete siblings. It does not explicitly contrast with set_memo_attachments, but the intent is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. The word 'existing' implies it is not for creation, but there is no explicit context, prerequisites, or mention of set_memo_attachments as a possible alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_memoC

Update an existing memo

ParametersJSON Schema
NameRequiredDescriptionDefault
stateNoNew state setting
memoIdYesThe memo ID to update
pinnedNoNew pinned state
contentNoNew content for the memo
visibilityNoNew visibility setting

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. Saying 'update' only implies mutation; it does not explain whether fields are replaced partially or entirely, whether the memo must exist, or what the response contains.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler, which is concise. However, it is under-specified for a tool with five parameters and no annotations, so the brevity is not fully appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with five parameters, no output schema, and no annotations, the description lacks sufficient context about invocation behavior and field semantics. An agent would need to infer too much about how to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 description adds no parameter-specific meaning beyond what the schema already provides, but the schema itself documents each parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb ('Update') and resource ('existing memo'), which distinguishes it from sibling tools like create_memo, get_memo, and delete_memo. The description is simple but unambiguous, though it adds little beyond the tool name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. It does not mention that create_memo is for new memos or that get_memo/list_memos might be needed before updating.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 12 tool updatesv1.0.0
    • First observedcreate_attachment
    • First observedcreate_memo
    • First observeddelete_attachment
    • First observeddelete_memo
    • First observedget_attachment
    • First observedget_memo
    • First observedlist_attachments
    • First observedlist_memo_attachments
    • First observedlist_memos
    • First observedset_memo_attachments
    • First observedupdate_attachment
    • First observedupdate_memo

TDQS

A3.7/5.0

Scored across 12 tools

Disambiguation5/5

Each tool clearly targets a distinct resource and action: memo CRUD, attachment CRUD, and attachment-memo relationship operations are separated. list_memo_attachments and list_attachments are distinguished by scope, and set_memo_attachments is clearly different from create_attachment because one associates existing attachments while the other creates them.

Naming Consistency5/5

All tools follow a consistent snake_case verb_noun pattern: create_, list_, get_, update_, delete_ with the resource clearly named. The relationship tools set_memo_attachments and list_memo_attachments also align with this convention.

Tool Count5/5

12 tools is well-scoped for a server managing two related resources with full CRUD plus relationship operations. Each tool earns its place, and the count is neither bloated nor too thin.

Completeness5/5

Both memos and attachments have complete lifecycle coverage: create, read, list, update, delete. The additional memo-attachment relationship tools provide the missing linking capability, and set_memo_attachments allows replacement or clearing of attachments, covering all obvious workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers