Skip to main content
Glama

YouGile Secure MCP

A local stdio Model Context Protocol server for the YouGile API v2. Read-only by default; writes require an explicit, single-use approval issued after the user confirms the exact payload in chat.

Tools (v0.2.0)

Read-only

Tool

Purpose

get_current_user

Profile that owns the API key

list_projects, get_project

Projects

list_boards, get_board

Boards

list_columns

Columns

list_tasks

Compact task summaries with server-side filters (column, assignee, title, sticker)

get_task

Full task object by UUID

find_task_by_short_id

Look up a task by human-readable ID such as ID-484 / DEV-484

list_task_comments

Task chat messages

list_users

Company users (filter by project or email)

list_string_stickers

Custom stickers and their states

All list tools return {"items": [...], "has_more": bool}; limit is capped at 100, use offset for the next page.

Staged writes (explicit approval required)

Tool

Purpose

propose_task_create

Stage a new task, returns a preview + single-use approval token

propose_task_update

Stage changes to an existing task, same contract

apply_approved_action

Execute a staged action; the only tool that can mutate YouGile

The flow is: agent stages an action → shows the preview to the user → the user approves in chat → agent calls apply_approved_action with the token. Tokens are bound to the exact payload, single-use, and expire after YOUGILE_APPROVAL_TTL_SECONDS (default 600). Delete operations are not implemented at all.

Security model

  • Uses only YOUGILE_API_KEY; never accepts, stores, or sends an account login/password.

  • Never creates, lists, or deletes YouGile API keys, webhooks, or users.

  • Never writes credentials to disk; API errors never include response bodies, so the key cannot leak through error messages.

  • All object IDs interpolated into URL paths are validated as UUIDs (no path traversal).

  • YOUGILE_BASE_URL must be https (plain http is allowed only for localhost).

  • Handles the YouGile rate limit (50 requests/minute) with bounded retries on HTTP 429.

Related MCP server: JIRA MCP Server

Install

git clone https://github.com/ropuwz-dot/MCP-Yougile.git
cd MCP-Yougile
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'   # Linux/macOS
# .venv\Scripts\python -m pip install -e .[dev]  # Windows

Run it with the API key in the environment:

export YOUGILE_API_KEY='your-api-key'         # Windows: $env:YOUGILE_API_KEY='your-api-key'
.venv/bin/python run_server.py                # Windows: .venv\Scripts\python run_server.py

Configuration

Variable

Default

Purpose

YOUGILE_API_KEY

— (required)

YouGile API v2 key

YOUGILE_BASE_URL

https://yougile.com

Self-hosted deployments: the mainPageUrl from your conf.json

YOUGILE_TIMEOUT_SECONDS

30

HTTP timeout

YOUGILE_APPROVAL_TTL_SECONDS

600

Lifetime of a staged write approval

YOUGILE_SSL_CA_CERT

Path to a CA bundle for self-hosted servers with a self-signed certificate

YOUGILE_ALLOW_INSECURE_HTTP

false

Explicit opt-in for plain-http local self-hosted servers

Self-hosted (box) YouGile

The self-hosted Linux Server edition exposes the same API v2 on your own domain. Point YOUGILE_BASE_URL at the mainPageUrl value from your conf.json:

  • HTTPS with a self-signed certificate — set YOUGILE_SSL_CA_CERT to the path of the certificate (or its CA) so TLS verification keeps working. Verification can never be turned off.

  • Plain HTTP on a trusted local network — allowed by YouGile for local use, but here it requires YOUGILE_ALLOW_INSECURE_HTTP=true so the API key is never sent in clear text by accident. http://localhost works without the flag.

Client configuration

Claude Code

claude mcp add yougile -e YOUGILE_API_KEY=your-api-key -- /absolute/path/to/MCP-Yougile/.venv/bin/python /absolute/path/to/MCP-Yougile/run_server.py

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "yougile": {
      "command": "/absolute/path/to/MCP-Yougile/.venv/bin/python",
      "args": ["/absolute/path/to/MCP-Yougile/run_server.py"],
      "env": { "YOUGILE_API_KEY": "your-api-key" }
    }
  }
}

Hermes

Keep the secret in ~/.hermes/.env with 0600 permissions:

YOUGILE_API_KEY=your-api-key

Then add this server under mcp_servers in ~/.hermes/config.yaml:

mcp_servers:
  yougile:
    command: /absolute/path/to/MCP-Yougile/.venv/bin/python
    args: [/absolute/path/to/MCP-Yougile/run_server.py]
    env:
      YOUGILE_API_KEY: "${YOUGILE_API_KEY}"
    timeout: 60
    connect_timeout: 30
    sampling:
      enabled: false

Verify it before restarting Hermes: hermes mcp test yougile.

Development

.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check src tests
.venv/bin/python -m mypy

CI runs the same three checks on Python 3.11–3.13 for every push and pull request.

License

MIT

Available Tools

15 tools
apply_approved_actionA

Execute a previously staged write action after the user explicitly approved it in chat. Requires the single-use approval token returned by a propose_* tool.

ParametersJSON Schema
NameRequiredDescriptionDefault
approval_tokenYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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

Description discloses it's a write action and single-use, adding to neutral annotations. Could detail token expiration or error cases.

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

Conciseness5/5

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and clear.

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

Completeness5/5

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

Complete for a simple tool with one parameter and an output schema. Covers usage pattern adequately.

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

Parameters4/5

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

Schema has 0% coverage, but description explains the token's origin and single-use property, adding useful meaning beyond schema.

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?

Description clearly states verb 'execute' and resource 'previously staged write action after user approval'. It distinguishes from sibling propose_* tools by being the execution counterpart.

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

Usage Guidelines4/5

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

Explicitly requires the approval token from propose_* tools, indicating when to use. Lacks explicit exclusions but context is clear.

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

find_task_by_short_idA
Read-onlyIdempotent

Find a task by its human-readable ID such as ID-484 (company-wide) or DEV-484 (project). Scans the task list, so it may be slow on large workspaces; prefer get_task when the UUID is known.

ParametersJSON Schema
NameRequiredDescriptionDefault
short_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior4/5

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

Annotations already indicate read-only and idempotent; description adds that it scans task list and may be slow, which is useful behavioral context.

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?

Two sentences, efficient, front-loaded with core purpose, no wasted words.

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

Completeness5/5

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 output schema present, the description covers input format, usage guidance, and performance caveat completely.

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

Parameters5/5

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

Schema has 0% description coverage, but description provides examples of valid short IDs (ID-484, DEV-484) and explains the format, adding critical meaning.

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?

Clearly states it finds a task by human-readable short ID, and distinguishes from get_task which uses UUID.

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

Usage Guidelines5/5

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

Explicitly says when to use (short ID known) and when to prefer get_task (UUID known), plus warns about slowness on large workspaces.

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

get_boardB
Read-onlyIdempotent

Get one board by its YouGile UUID.

ParametersJSON Schema
NameRequiredDescriptionDefault
board_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds no behavioral context beyond this, such as permissions, error handling, or rate limits. It relies entirely on the annotations.

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, front-loaded sentence with no wasted words. However, it is overly minimal and could include more detail without sacrificing conciseness.

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?

Given the simple nature of the tool (get by ID) and the presence of an output schema, the description is adequate but incomplete. The lack of parameter documentation and any behavioral notes leaves gaps for the agent.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain the parameter 'board_id' (e.g., format, example, or note about UUID). The agent has no additional meaning beyond the schema's type and title, making it hard to invoke correctly.

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 verb 'Get' and the resource 'one board by its YouGile UUID', specifying both the action and the identifier. This distinguishes it from siblings like list_boards (which returns multiple boards) and get_task (different resource).

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 implies usage for retrieving a single board by UUID, but does not explicitly state when to use it versus alternatives like list_boards. No exclusions or prerequisites are provided, leaving the agent to infer context from the sibling tool names.

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

get_current_userA
Read-onlyIdempotent

Get the user profile that owns the configured YouGile API key.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the important context that the result is tied to the configured API key owner, which is valuable beyond the annotations. No contradictions.

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 sentence, perfectly concise with no wasted words. It provides exactly the necessary information without extraneous content.

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

Completeness5/5

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

Given the tool has no parameters, an output schema (not shown), and thorough annotations, the description is complete. It explains the purpose and the scope (API key owner), which is all an agent needs to invoke it correctly.

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

Parameters4/5

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

The tool has zero parameters, and the schema coverage is 100%. The description correctly adds no parameter details, as no parameters exist. According to guidelines, parameter semantics scores baseline 4 for zero-parameter tools.

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 tool retrieves the user profile that owns the configured API key. It uses a specific verb ('Get') and resource ('user profile'), and uniquely identifies the scope (the current API key owner), differentiating it from any sibling tools that might list all users or retrieve other user profiles.

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

Usage Guidelines4/5

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

The description implicitly indicates when to use the tool (to get the current user's profile), but it does not explicitly state when not to use it or provide comparisons with sibling tools like list_users. Given the simple scope, the guideline is clear enough for an agent.

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

get_projectA
Read-onlyIdempotent

Get one project by its YouGile UUID.

ParametersJSON Schema
NameRequiredDescriptionDefault
project_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

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

Annotations indicate readOnlyHint=true and idempotentHint=true, which the description does not contradict. Description adds context about the UUID but no additional behavioral traits beyond the annotations.

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?

Single sentence, no wasted words, front-loaded with the key action and resource.

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

Completeness5/5

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

Given low complexity (1 required parameter, read-only operation, annotations present, and output schema exists), the description sufficiently covers what the tool does.

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

Parameters4/5

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

With 0% schema description coverage, the description compensates by clarifying that the project_id is a 'YouGile UUID', adding meaning beyond the generic 'Project Id' title in the schema.

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?

Description states 'Get one project by its YouGile UUID' with a specific verb and resource, clearly differentiating from list_projects which returns multiple projects.

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 on when to use this tool versus alternatives like list_projects. The description only states what it does, not the context for its use.

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

get_taskA
Read-onlyIdempotent

Get one task with all fields by its YouGile UUID.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds that the tool returns 'all fields', which is valuable context beyond annotations. There is no contradiction between description and annotations.

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 sentence of 10 words with no extraneous information. It is front-loaded with the key action and purpose.

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

Completeness5/5

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, good annotations, output schema present), the description sufficiently covers what the tool does, what it returns, and how to identify the resource. No additional context is needed.

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

Parameters4/5

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

The single parameter 'task_id' has 0% schema description coverage, but the description clarifies it is a 'YouGile UUID', adding semantic meaning beyond the schema's generic 'string' type and title 'Task Id'.

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 verb 'Get', the resource 'one task', the scope 'with all fields', and the identifier type 'YouGile UUID'. This distinguishes it from sibling tools like list_tasks (multiple tasks) and find_task_by_short_id (different identifier).

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 implies usage when retrieving a single task by UUID but provides no explicit guidance on when to use this tool versus alternatives, such as find_task_by_short_id or list_tasks, nor does it mention exclusions or prerequisites.

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

list_boardsA
Read-onlyIdempotent

List boards, optionally narrowed to a project. Returns items plus has_more; limit is capped at 100.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
offsetNo
project_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds extra context: returns structure (items plus has_more) and limit cap at 100, which is useful beyond annotations.

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?

Single sentence that efficiently conveys main purpose, optional filter, return fields, and a constraint. No wasted words.

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

Completeness4/5

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

Given output schema exists, description's mention of 'items plus has_more' is sufficient for pagination context. Could include ordering or error info, but overall adequate for a read-only list tool with simple parameters.

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 0%, but parameter names (limit, offset, project_id) are mostly self-explanatory. Description adds that limit is capped at 100 and project_id narrows to a project, providing some semantics beyond schema.

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?

Description states the verb 'List' and resource 'boards', with optional narrowing to a project. Clearly distinguishes from siblings like list_projects (lists projects) and get_board (single board).

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?

No explicit guidance on when to use list_boards vs alternatives. The description implies it for listing boards, but lacks when-not-to-use or comparison with siblings like get_board for single boards.

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

list_columnsA
Read-onlyIdempotent

List columns, optionally narrowed to a board. Returns items plus has_more; limit is capped at 100.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
offsetNo
board_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and non-destructive, but the description adds key behavioral details: limit cap at 100 and pagination indicator 'has_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, front-loading the action and adding critical constraints without fluff.

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

Completeness5/5

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

The description is complete for a simple list tool: it covers purpose, optional filtering, pagination, and a hard cap. Output schema handles return values.

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?

With 0% schema coverage, the description explains board_id ('optionally narrowed to a board') and limit cap, but omits explicit semantics for offset and default values.

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 tool lists columns and optionally narrows by board, with distinct language from sibling list_* tools.

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

Usage Guidelines4/5

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

The description provides clear context for use (listing columns, optionally by board) but does not explicitly mention when not to use or differentiate from siblings.

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

list_projectsA
Read-onlyIdempotent

List projects visible to the configured YouGile API key. Returns items plus has_more; limit is capped at 100, use offset to fetch the next page.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
offsetNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. Description adds pagination behavior (limit cap, offset usage) beyond annotations, providing useful operational details.

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?

Two sentences: first states purpose, second adds pagination details. No wasted words, front-loaded with the action.

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

Completeness5/5

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

With output schema present, description does not need to detail return format. It covers pagination and the items/has_more response. Combined with annotations, all necessary context is provided.

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

Parameters4/5

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

Schema coverage is 0%, so description carries full burden. It explains that limit is capped at 100 and offset is for pagination, which adds meaning beyond the schema's type and defaults.

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?

Description clearly states 'List projects visible to the configured YouGile API key', using a specific verb and resource. It is distinct from siblings like get_project (single project) and other list tools (different entities).

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

Usage Guidelines4/5

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

Provides explicit context: 'limit is capped at 100, use offset to fetch the next page', telling how to paginate. Though it does not explicitly state when not to use, the context implies usage for listing all projects.

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

list_string_stickersA
Read-onlyIdempotent

List custom stickers with their states, optionally narrowed to a board. Needed to decode task sticker values. Returns items plus has_more; limit is capped at 100.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
offsetNo
board_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds pagination details (has_more, limit capped at 100) and optional board filtering, providing behavioral context beyond annotations.

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?

Two sentences, front-loaded with verb and object, immediate purpose, and key details. No redundant or superfluous words.

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

Completeness4/5

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

Covers purpose, parameter hints, pagination, and limit cap. Output schema exists (not shown) so missing return field details is acceptable. Slightly lacks offset description but acceptable given tool simplicity.

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

Parameters4/5

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

Schema has 0% description coverage, so description compensates by mentioning 'optionally narrowed to a board' (board_id) and 'limit is capped at 100' (limit), plus pagination implies offset. All three parameters are addressed implicitly or explicitly.

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?

Clearly states verb 'list', resource 'custom stickers with their states', optional board filter, purpose for decoding task stickers, return shape (items+has_more), and limit cap. Distinguishes from sibling list tools by specific resource and context.

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

Usage Guidelines4/5

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

Explicitly says 'Needed to decode task sticker values', giving a clear use case. Lacks explicit when-not or alternatives, but sibling tools are sufficiently different.

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

list_task_commentsA
Read-onlyIdempotent

List chat messages (comments) of a task, oldest first. Returns items plus has_more; limit is capped at 100.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
sinceNo
offsetNo
task_idYes
include_systemNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: returns both items and has_more, limit is capped at 100, and ordering is oldest first. This exceeds what annotations provide.

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?

Two sentences, no filler, front-loaded with purpose. Every word is useful and concise.

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?

Given the presence of an output schema and annotations, the description is adequate but missing parameter semantics for 4 out of 5 parameters. The tool has moderate complexity (5 params) and needs more parameter explanation for full completeness.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It only explains the limit parameter's cap (100). Other parameters (since, offset, include_system, task_id) are not described, leaving the agent guessing their meaning.

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'), the resource ('chat messages (comments) of a task'), and the ordering ('oldest first'). It is distinct from sibling tools which focus on boards, tasks, projects, etc.

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?

No guidance on when to use this tool versus alternatives (e.g., maybe other comment retrieval methods). The description implies context but does not explicitly state when or when not to use it.

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

list_tasksA
Read-onlyIdempotent

List tasks with server-side filters. Returns compact task summaries plus has_more (use get_task for the full object); limit is capped at 100. assigned_to accepts comma-separated user UUIDs.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
titleNo
offsetNo
column_idNo
sticker_idNo
assigned_toNo
sticker_state_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare read-only and idempotent behavior. Description adds that results are compact summaries with has_more indicator and that limit is capped at 100. However, pagination behavior (offset usage) and error scenarios are 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.

Conciseness5/5

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

Two sentences, front-loaded with action and filtering nature. No wasted words; structure is efficient.

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?

Despite having output schema, the description fails to cover the semantics of most input parameters (5 of 7 undocumented). Pagination via offset and has_more is implied but not explained. Lacks details on ordering or other constraints.

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

Parameters2/5

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

With 0% schema coverage, description must clarify parameters. Only assigned_to (comma-separated UUIDs) and limit (capped at 100) are explained. The other five parameters (title, offset, column_id, sticker_id, sticker_state_id) are left undocumented, requiring inference.

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?

Description clearly states it lists tasks with server-side filters and distinguishes itself from get_task by noting it returns compact summaries with has_more. Purpose is unambiguous and differentiates from sibling.

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

Usage Guidelines4/5

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

Explicitly tells when to use get_task for full objects and notes limit cap of 100. Lacks guidance on when to use alternative list tools or pagination usage, but provides sufficient context for basic use.

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

list_usersA
Read-onlyIdempotent

List company users, optionally filtered by project or email. Returns items plus has_more; limit is capped at 100.

ParametersJSON Schema
NameRequiredDescriptionDefault
emailNo
limitNo
offsetNo
project_idNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context about return format (items plus has_more) and the limit cap, which goes beyond annotations. No contradiction found.

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 two sentences, front-loads the main action, and contains no unnecessary words. Every sentence adds value.

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

Completeness4/5

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

The tool has 4 optional parameters and an output schema. The description covers two filters and the limit cap, and mentions return fields. Offset is missing, but overall the description is sufficient for a list tool with standard pagination.

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?

With 0% schema description coverage, the description must compensate. It mentions filtering by project or email and a limit cap of 100, but does not explain offset or the exact meaning of parameters. The schema defaults are present but the description adds only partial clarity.

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 tool lists company users with optional filters by project or email, and specifies the return format with items and has_more, plus a limit cap. This verb+resource statement is specific and distinguishes from sibling tools like list_projects or list_tasks.

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

Usage Guidelines4/5

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

The description indicates optional filtering and a limit cap, but does not explicitly state when to use this tool over alternatives. However, sibling tools are clearly different in purpose, so the usage context is implied.

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

propose_task_createA
Read-onlyIdempotent

Stage the creation of a task and get an approval token. Does NOT create anything: show the preview to the user, and only after the user explicitly approves call apply_approved_action with the token.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYes
assignedNo
column_idYes
descriptionNo
extra_fieldsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior5/5

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

Annotations already indicate read-only and non-destructive behavior. The description adds critical behavioral context: the tool does not create anything; it only stages and returns a token, requiring a second step. This is beyond what annotations convey.

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?

Two sentences that are front-loaded with purpose and immediate behavioral constraint. Every word adds value; no redundancy or waste.

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?

Given the tool is part of a two-step approval workflow, the description explains the flow and return token. However, the lack of parameter documentation reduces completeness for proper invocation. The output schema exists but is not referenced.

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

Parameters1/5

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

With 0% schema description coverage, the description must compensate for parameter meaning, but it provides no details about title, column_id, assigned, description, or extra_fields. The agent receives no guidance on parameter usage.

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 tool stages task creation and returns an approval token, distinct from actual creation. It explicitly says 'Does NOT create anything', which separates it from sibling propose_task_update and apply_approved_action.

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

Usage Guidelines4/5

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

The description provides clear context: show preview to user, get token, then use apply_approved_action upon approval. It implies a two-step workflow but does not explicitly state when to prefer this over propose_task_update or other tools.

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

propose_task_updateA
Read-onlyIdempotent

Stage an update of an existing task and get an approval token. Does NOT change anything: show the preview to the user, and only after the user explicitly approves call apply_approved_action with the token. Allowed change fields: archived, assigned, checklists, color, columnId, completed, deadline, description, stickers, subtasks, timeTracking, title. Deleting tasks is not supported.

ParametersJSON Schema
NameRequiredDescriptionDefault
changesYes
task_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds crucial context: the tool does NOT make changes, requires user approval via a token, and lists permissible fields. This exceeds what annotations convey.

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?

Two concise, front-loaded sentences cover the entire functionality, usage flow, and constraints without superfluous information.

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

Completeness5/5

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

Given the tool's moderate complexity (2 params, nested object), the description fully equips an agent to understand when and how to use it, what it doesn't do, and how it relates to siblings. Output schema exists for return details.

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

Parameters4/5

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

With schema coverage at 0%, the description compensates by listing allowed change fields (archived, assigned, etc.) and explaining the purpose of the token. However, the 'changes' object structure remains vaguely defined as additionalProperties, not detailing value types.

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 tool stages an update and provides an approval token, explicitly noting it does NOT change anything. It lists allowed fields and clarifies deletion is unsupported, distinguishing it from sibling apply_approved_action.

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

Usage Guidelines5/5

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

The description provides explicit guidance: show preview to user, then call apply_approved_action with token after approval. It also lists allowed field modifications and states that task deletion is not supported, leaving no ambiguity.

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. 15 tool updatesv0.2.1
    • Addedapply_approved_action
    • Addedfind_task_by_short_id
    • Addedget_board
    • Addedget_current_user
    • Addedget_project
    • Changedget_task1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
        +  "additionalProperties": true,
        +  "title": "get_taskDictOutput",
        +  "type": "object"
        +}
    • Changedlist_boards4 fields changed
      • addedOutput schema / additionalProperties
        Added value: +true
      • removedOutput schema / properties
        Removed value: -{
        -  "result": {
        -    "items": {
        -      "additionalProperties": true,
        -      "type": "object"
        -    },
        -    "title": "Result",
        -    "type": "array"
        -  }
        -}
      • removedOutput schema / required
        Removed value: -[
        -  "result"
        -]
      • changedOutput schema / title
        Previous value: -"list_boardsOutput"New value: +"list_boardsDictOutput"
    • Changedlist_columns6 fields changed
      • addedInput schema / properties / limit
        Added value: +{
        +  "default": 50,
        +  "title": "Limit",
        +  "type": "integer"
        +}
      • addedInput schema / properties / offset
        Added value: +{
        +  "default": 0,
        +  "title": "Offset",
        +  "type": "integer"
        +}
      • addedOutput schema / additionalProperties
        Added value: +true
      • removedOutput schema / properties
        Removed value: -{
        -  "result": {
        -    "items": {
        -      "additionalProperties": true,
        -      "type": "object"
        -    },
        -    "title": "Result",
        -    "type": "array"
        -  }
        -}
      • removedOutput schema / required
        Removed value: -[
        -  "result"
        -]
      • changedOutput schema / title
        Previous value: -"list_columnsOutput"New value: +"list_columnsDictOutput"
    • Changedlist_projects4 fields changed
      • addedOutput schema / additionalProperties
        Added value: +true
      • removedOutput schema / properties
        Removed value: -{
        -  "result": {
        -    "items": {
        -      "additionalProperties": true,
        -      "type": "object"
        -    },
        -    "title": "Result",
        -    "type": "array"
        -  }
        -}
      • removedOutput schema / required
        Removed value: -[
        -  "result"
        -]
      • changedOutput schema / title
        Previous value: -"list_projectsOutput"New value: +"list_projectsDictOutput"
    • Addedlist_string_stickers
    • Addedlist_task_comments
    • Changedlist_tasks6 fields changed
      • addedInput schema / properties / sticker_id
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "string"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null,
        +  "title": "Sticker Id"
        +}
      • addedInput schema / properties / sticker_state_id
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "string"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null,
        +  "title": "Sticker State Id"
        +}
      • addedOutput schema / additionalProperties
        Added value: +true
      • removedOutput schema / properties
        Removed value: -{
        -  "result": {
        -    "items": {
        -      "additionalProperties": true,
        -      "type": "object"
        -    },
        -    "title": "Result",
        -    "type": "array"
        -  }
        -}
      • removedOutput schema / required
        Removed value: -[
        -  "result"
        -]
      • changedOutput schema / title
        Previous value: -"list_tasksOutput"New value: +"list_tasksDictOutput"
    • Changedlist_users8 fields changed
      • addedInput schema / properties / email
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "string"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null,
        +  "title": "Email"
        +}
      • addedInput schema / properties / limit
        Added value: +{
        +  "default": 50,
        +  "title": "Limit",
        +  "type": "integer"
        +}
      • addedInput schema / properties / offset
        Added value: +{
        +  "default": 0,
        +  "title": "Offset",
        +  "type": "integer"
        +}
      • addedInput schema / properties / project_id
        Added value: +{
        +  "anyOf": [
        +    {
        +      "type": "string"
        +    },
        +    {
        +      "type": "null"
        +    }
        +  ],
        +  "default": null,
        +  "title": "Project Id"
        +}
      • addedOutput schema / additionalProperties
        Added value: +true
      • removedOutput schema / properties
        Removed value: -{
        -  "result": {
        -    "items": {
        -      "additionalProperties": true,
        -      "type": "object"
        -    },
        -    "title": "Result",
        -    "type": "array"
        -  }
        -}
      • removedOutput schema / required
        Removed value: -[
        -  "result"
        -]
      • changedOutput schema / title
        Previous value: -"list_usersOutput"New value: +"list_usersDictOutput"
    • Addedpropose_task_create
    • Addedpropose_task_update
  2. 6 tool updatesv0.1.0
    • First observedget_task
    • First observedlist_boards
    • First observedlist_columns
    • First observedlist_projects
    • First observedlist_tasks
    • First observedlist_users

TDQS

A4.1/5.0

Scored across 15 tools

Disambiguation5/5

Each tool targets a distinct resource or action. Read tools (get_*, list_*) are separate from write tools (propose_*, apply_approved_action). The find_task_by_short_id is unique. No overlapping purposes.

Naming Consistency5/5

All tool names use lower_snake_case and follow a verb_noun pattern. Verbs are consistently get_, list_, find_, propose_, apply_. No mixing of conventions.

Tool Count5/5

15 tools is appropriate for a project management server. It covers listing and getting all major entities, plus a safe write pattern, without being excessive or too sparse.

Completeness4/5

Covers reading all entities and creating/updating tasks with a safe approval pattern. Missing delete for tasks and modifications for boards/columns/projects, but these are reasonable omissions given the secure nature.

Maintenance

ActivityStale
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    F
    maintenance
    MCP server for YouGile project management. Provides 57 tools covering 100% of YouGile API v2, enabling natural language management of projects, boards, columns, tasks, chats, users, and more.
    57
    31 npm
    9
    MIT