YouGile Secure MCP
This server provides a secure, read-first interface to the YouGile API v2 over MCP, with staged user-approved write operations for tasks.
Read-Only Tools
User: Get the profile of the API key owner (
get_current_user)Projects: List all projects or get one by UUID (
list_projects,get_project)Boards: List boards (optionally by project) or get one by UUID (
list_boards,get_board)Columns: List columns, optionally filtered by board (
list_columns)Tasks: List compact summaries with filters, get a full task by UUID, or find a task by human-readable short ID like
DEV-484(list_tasks,get_task,find_task_by_short_id)Comments: List comments on a task, oldest first (
list_task_comments)Users: List company users, optionally filtered by project or email (
list_users)Stickers: List custom stickers and their states (
list_string_stickers)All list tools support pagination (
limitcapped at 100,offset), returning ahas_moreflag
Staged Write Tools (require explicit user approval)
propose_task_create– Stage a new task (title, column, assignees, description, extra fields); returns a preview + single-use approval tokenpropose_task_update– Stage changes to an existing task (title, description, assignees, columnId, deadline, completed, archived, color, stickers, checklists, subtasks, timeTracking); returns a preview + approval tokenapply_approved_action– The only tool that mutates YouGile data; executes a staged action using its approval token after the user confirms in chat
Notable Constraints
Delete operations are not supported
Approval tokens are single-use and expire after a configurable TTL (default 10 minutes)
No login/password handling — API key only; no key leakage via error messages
UUID validation on all object IDs; HTTPS enforced for non-localhost base URLs
Supports self-hosted YouGile instances with custom base URL, SSL CA cert, and localhost HTTP opt-in
Provides read-only access to YouGile project management API, designed for use with Hermes Agent.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@YouGile Secure MCPshow me all my projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Profile that owns the API key |
| Projects |
| Boards |
| Columns |
| Compact task summaries with server-side filters (column, assignee, title, sticker) |
| Full task object by UUID |
| Look up a task by human-readable ID such as |
| Task chat messages |
| Company users (filter by project or email) |
| 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 |
| Stage a new task, returns a preview + single-use approval token |
| Stage changes to an existing task, same contract |
| 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_URLmust behttps(plainhttpis 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] # WindowsRun 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.pyConfiguration
Variable | Default | Purpose |
| — (required) | YouGile API v2 key |
|
| Self-hosted deployments: the |
|
| HTTP timeout |
|
| Lifetime of a staged write approval |
| — | Path to a CA bundle for self-hosted servers with a self-signed certificate |
|
| 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_CERTto 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=trueso the API key is never sent in clear text by accident.http://localhostworks 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.pyClaude 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-keyThen 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: falseVerify 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 mypyCI runs the same three checks on Python 3.11–3.13 for every push and pull request.
License
Available Tools
15 toolsapply_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.
| Name | Required | Description | Default |
|---|---|---|---|
| approval_token | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_idARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| short_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_boardBRead-onlyIdempotent
Get one board by its YouGile UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| board_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_userARead-onlyIdempotent
Get the user profile that owns the configured YouGile API key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_projectARead-onlyIdempotent
Get one project by its YouGile UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_taskARead-onlyIdempotent
Get one task with all fields by its YouGile UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_boardsARead-onlyIdempotent
List boards, optionally narrowed to a project. Returns items plus has_more; limit is capped at 100.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| project_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_columnsARead-onlyIdempotent
List columns, optionally narrowed to a board. Returns items plus has_more; limit is capped at 100.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| board_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_projectsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_stickersARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| board_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_commentsARead-onlyIdempotent
List chat messages (comments) of a task, oldest first. Returns items plus has_more; limit is capped at 100.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| since | No | ||
| offset | No | ||
| task_id | Yes | ||
| include_system | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_tasksARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| title | No | ||
| offset | No | ||
| column_id | No | ||
| sticker_id | No | ||
| assigned_to | No | ||
| sticker_state_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_usersARead-onlyIdempotent
List company users, optionally filtered by project or email. Returns items plus has_more; limit is capped at 100.
| Name | Required | Description | Default |
|---|---|---|---|
| No | |||
| limit | No | ||
| offset | No | ||
| project_id | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_createARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| assigned | No | ||
| column_id | Yes | ||
| description | No | ||
| extra_fields | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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_updateARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes | ||
| task_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
15 tool updates
v0.2.1- Added
apply_approved_action - Added
find_task_by_short_id - Added
get_board - Added
get_current_user - Added
get_project - Changed
get_task1 field changed- changed
Output schema / (root)Previous value: -nullNew value: +{ + "additionalProperties": true, + "title": "get_taskDictOutput", + "type": "object" +}
- Changed
list_boards4 fields changed- added
Output schema / additionalPropertiesAdded value: +true - removed
Output schema / propertiesRemoved value: -{ - "result": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "title": "Result", - "type": "array" - } -} - removed
Output schema / requiredRemoved value: -[ - "result" -] - changed
Output schema / titlePrevious value: -"list_boardsOutput"New value: +"list_boardsDictOutput"
- Changed
list_columns6 fields changed- added
Input schema / properties / limitAdded value: +{ + "default": 50, + "title": "Limit", + "type": "integer" +} - added
Input schema / properties / offsetAdded value: +{ + "default": 0, + "title": "Offset", + "type": "integer" +} - added
Output schema / additionalPropertiesAdded value: +true - removed
Output schema / propertiesRemoved value: -{ - "result": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "title": "Result", - "type": "array" - } -} - removed
Output schema / requiredRemoved value: -[ - "result" -] - changed
Output schema / titlePrevious value: -"list_columnsOutput"New value: +"list_columnsDictOutput"
- Changed
list_projects4 fields changed- added
Output schema / additionalPropertiesAdded value: +true - removed
Output schema / propertiesRemoved value: -{ - "result": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "title": "Result", - "type": "array" - } -} - removed
Output schema / requiredRemoved value: -[ - "result" -] - changed
Output schema / titlePrevious value: -"list_projectsOutput"New value: +"list_projectsDictOutput"
- Added
list_string_stickers - Added
list_task_comments - Changed
list_tasks6 fields changed- added
Input schema / properties / sticker_idAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Sticker Id" +} - added
Input schema / properties / sticker_state_idAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Sticker State Id" +} - added
Output schema / additionalPropertiesAdded value: +true - removed
Output schema / propertiesRemoved value: -{ - "result": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "title": "Result", - "type": "array" - } -} - removed
Output schema / requiredRemoved value: -[ - "result" -] - changed
Output schema / titlePrevious value: -"list_tasksOutput"New value: +"list_tasksDictOutput"
- Changed
list_users8 fields changed- added
Input schema / properties / emailAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Email" +} - added
Input schema / properties / limitAdded value: +{ + "default": 50, + "title": "Limit", + "type": "integer" +} - added
Input schema / properties / offsetAdded value: +{ + "default": 0, + "title": "Offset", + "type": "integer" +} - added
Input schema / properties / project_idAdded value: +{ + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "default": null, + "title": "Project Id" +} - added
Output schema / additionalPropertiesAdded value: +true - removed
Output schema / propertiesRemoved value: -{ - "result": { - "items": { - "additionalProperties": true, - "type": "object" - }, - "title": "Result", - "type": "array" - } -} - removed
Output schema / requiredRemoved value: -[ - "result" -] - changed
Output schema / titlePrevious value: -"list_usersOutput"New value: +"list_usersDictOutput"
- Added
propose_task_create - Added
propose_task_update
6 tool updates
v0.1.0- First observed
get_task - First observed
list_boards - First observed
list_columns - First observed
list_projects - First observed
list_tasks - First observed
list_users
TDQS
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Read teams, spaces, lists and tasks; create, update and comment on tasks and track time.
Read-only access to a Zoopit account: orders, routes, fleet and live vehicle positions.
Read-only NuMetric.work accounting & ERP data: statements, KPIs, reports, invoices, documents.
- PithflowOAuthcom.pithflow
Read-only access to your own Pithflow meeting notes, transcripts, dictionary and usage.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and developer tools to interact programmatically with Yougile workspace, supporting project, task, user, board, and column management through natural language.6 npm20MIT
- AlicenseAqualityDmaintenanceProvides read-only access to JIRA REST API, enabling LLMs to query and retrieve information from JIRA instances.147 npmMIT
- FlicenseNot gradedqualityDmaintenanceIntegrates with YouGile to allow AI assistants to create, update, and manage projects, tasks, and team members via the MCP protocol.12-
- AlicenseAqualityFmaintenanceMCP 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.5731 npm9MIT