This server wraps the Upservice Public API, providing tools to manage employees, projects, sprints, tasks, tags, directories, and chat/channel communications.
Employees — List employees in the account.
Projects — List, create, get, update, delete projects; set managers/members; mark as completed.
Sprints — List, create, get, update, delete sprints; activate or complete sprints; add tasks to a sprint.
Tags — List, create, update, delete tags; assign/unassign to tasks, chats, assets, contacts, or attachments.
Tasks — List/search (with filters), create (task, meeting, agreement, acquaintance, ticket, etc.), get, update, delete; manage attachments, status, effort estimation, worklog, agreement/approval workflow, co-responsibles, agreement sheets, and acquaintance sheets.
Directories — List, create, get, update, delete directories and their records; bulk add/remove relations between records and other entities (tasks, projects, orders, etc.).
Channels & Files — Load/send chat messages, send channel messages, create external messages, upload files (general or channel-scoped), and get time-limited file download URLs.
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., "@upservice-mcp list all 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.
An MCP (Model Context Protocol) server that wraps the Upservice Public API so Claude (or any MCP client) can manage employees, projects, sprints, tasks, tags, directories, and channel messages directly.
Built from the OpenAPI spec at https://public.upservice.io/openapi.json, verified against the live API.
58 tools covering:
Employees — list employees
Projects — list, create, get, update, delete, set managers/members, mark completed
Sprints — list, create, get, update, delete, complete, activate, add tasks
Tags — list, create, update, delete, assign/unassign to tasks/chats/assets/contacts/attachments
Tasks — list/search, create, get, update, delete, attachments, status changes, effort estimation, worklog, agreement (approval) workflow actions, co-responsibles, agreement/acquaintance sheets
Directories (custom reference catalogs) — list/create/get/update/delete directories and their records, plus bulk relation management (linking records to tasks, projects, orders, etc.)
Channels & files — load/send chat messages, send channel messages, upload files, get file download URLs
Every write tool exposes the well-documented fields explicitly (validated), and most also accept an extra_fields dict for advanced/uncommon fields documented in the Upservice API but not modeled individually.
Mentioning employees: Upservice only turns @Name into a real, notifying mention if it's written as @[Name](employee_id). Tools that write text (upservice_send_chat_message, upservice_send_channel_message, upservice_create_task, upservice_update_task) accept a mentions: [{employee_id, display_name}] field — put a {{employee_id}} placeholder in your text and the server substitutes the correct syntax for you.
Known API limitation: GET /v1/tasks (used by upservice_list_tasks) has no status/is_completed filter — confirmed against the live API, not just the docs. Filter by status client-side after narrowing with date_end_gte/date_end_lte, project, author, or responsible.
Related MCP server: Unipile Universal MCP Server
Get your Upservice API key first: in your Upservice account, go to account settings → API key. Keys look like UPS-XXXX-XXXX-XXXX-XXXX.
uvx (recommended, no manual install)Requires uv installed (brew install uv or see their docs). Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"upservice": {
"command": "uvx",
"args": ["--from", "/absolute/path/to/upservice_mcp", "upservice-mcp"],
"env": {
"UPSERVICE_API_KEY": "UPS-XXXX-XXXX-XXXX-XXXX"
}
}
}
}If this project is published to a git remote, --from can point at it directly instead of a local path:
"args": ["--from", "git+https://github.com/alexherbaly/upservice-mcp", "upservice-mcp"] — then a colleague only needs the URL and their own API key, no file copying at all.
Pin to a ref rather than the bare URL — without one, uvx tracks the main branch, so a bad push to main breaks everyone's server on their next run. Two options:
@stable (recommended for colleagues) — a tag that CI automatically moves to the tip of main every time the build passes. No one has to remember to cut a release for routine fixes; everyone's server just picks up the latest known-good commit next time it restarts.
@v0.2.0 (a specific version) — frozen forever at that exact commit, for when you want a name you can point back to later (release notes, "the version we tested on date X"). Cut these manually with git tag when it's worth a name, not on every push.
Example: "args": ["--from", "git+https://github.com/alexherbaly/upservice-mcp@stable", "upservice-mcp"]
uv builds and caches an isolated environment on first run; nothing is installed system-wide.
cd upservice_mcp
python3 -m venv venv
venv/bin/pip install -r requirements.txt{
"mcpServers": {
"upservice": {
"command": "/absolute/path/to/upservice_mcp/venv/bin/python3",
"args": ["/absolute/path/to/upservice_mcp/src/upservice_mcp/server.py"],
"env": {
"UPSERVICE_API_KEY": "UPS-XXXX-XXXX-XXXX-XXXX"
}
}
}
}Restart Claude Desktop afterwards. The tools will appear prefixed with upservice_.
If Upservice ever changes the API host, or you use a private/on-prem instance, override it:
"env": {
"UPSERVICE_API_KEY": "UPS-XXXX-XXXX-XXXX-XXXX",
"UPSERVICE_API_BASE_URL": "https://public.upservice.io"
}# uvx
UPSERVICE_API_KEY=UPS-XXXX uvx --from . upservice-mcp
# venv
UPSERVICE_API_KEY=UPS-XXXX venv/bin/python3 src/upservice_mcp/server.pyOr test interactively with the MCP Inspector:
npx @modelcontextprotocol/inspector uvx --from . upservice-mcpAuthentication uses a raw API key in the Authorization header (not a Bearer token) — this server handles that for you.
Destructive tools (delete_*, unassign_tag) are annotated with destructiveHint: true so MCP clients can warn users appropriately.
Some request bodies documented by Upservice have many optional fields; where a tool doesn't model a field explicitly, pass it via extra_fields (a plain JSON object) and it will be merged into the request body.
Never share your own UPSERVICE_API_KEY — each person should generate their own from their Upservice account settings.
Activate a sprint (start it).
Args: params (SprintIdInput): sprint_id (int)
Returns: str: JSON of the updated sprint.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotency, non-read-only, non-destructive hints. Description adds only 'start it' which rephrases activation. No additional behavioral details 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?
Very concise with a clear first sentence. Includes docstring-style sections, but the args/returns section partially duplicates schema info. Could be slightly more front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with one parameter and output schema present, the description covers basic purpose and return. Missing error conditions or preconditions, but annotations fill some gaps.
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% per context signals, meaning the schema lacks descriptions. The description minimally restates 'sprint_id (int)' without adding new meaning like constraints or data format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Activate a sprint' and parenthetically explains 'start it'. Differentiates from sibling tools like upservice_complete_sprint, upservice_create_sprint, and upservice_delete_sprint.
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. Does not mention prerequisites, conditions, or when not to use. Lacks context for selecting this over related sprint tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one or more existing tasks to a sprint.
Args: params (AddTasksToSprintInput): sprint_id (int), tasks (List[int] of task IDs)
Returns: str: JSON list of task IDs now in the sprint.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's not read-only, not idempotent, and not destructive, but the description only adds that the return is a JSON list of task IDs. Missing behavioral details such as what happens if a task is already in the sprint or if the sprint/task does not exist. With no annotation contradictions, the description provides moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an Args/Returns block, which is efficient and front-loaded with purpose. No unnecessary words, though the structure could be more natural. Overall, it is appropriately sized for the tool's simplicity.
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 is simple, and an output schema exists (not shown) but the description already covers the return format. However, it omits potential error conditions, idempotency behavior, and prerequisites like sprint/task existence. The description is adequate but not fully comprehensive for an agent to handle edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists the parameters 'sprint_id (int), tasks (List[int] of task IDs)' but this directly mirrors the input schema's property descriptions. Schema description coverage is 0% for top-level params, but the nested schema fields have descriptions. The tool description adds no new semantic meaning beyond the schema, just restates types and constraints already present.
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 'Add one or more existing tasks to a sprint.' The verb 'Add' and resource 'tasks to a sprint' are specific. The sibling tools (e.g., upservice_create_task, upservice_delete_task) are distinct, and the description explicitly mentions 'existing tasks', differentiating it from creation 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 does not explicitly state when to use this tool vs alternatives, nor does it mention prerequisites like the sprint or tasks must exist. The usage is implied but not directly guided; an agent could infer that this is for associating pre-existing tasks with a sprint, but no exclusions or comparison to siblings are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign (attach) a tag to an entity such as a task, chat, asset, contact, or attachment.
Args: params (AssignTagInput): tag_id (UUID), entity_id (UUID or int), entity_type (enum)
Returns: str: JSON confirmation of the assignment.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive behavior. The description adds that the tool returns a JSON confirmation string, and lists the attribute types. It does not detail potential side effects or prerequisites, but overall provides useful 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?
The description is a single, well-structured paragraph with action, entity types, args, and returns. Every sentence is useful, and there is no redundant or extraneous 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 simplicity (3 required nested params, straightforward assignment action), the description covers the main purpose, allowed entities, and return format. It does not address error conditions or entity existence prerequisites, but is largely complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description reiterates the three parameters (tag_id, entity_id, entity_type) with types, which adds slight value since the input schema already contains descriptions. With schema description coverage at 0% (likely a misreading), the description compensates only modestly, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Assign (attach) a tag to an entity' and lists specific entity types (task, chat, asset, contact, attachment), distinguishing it from sibling tools like upservice_create_tag, upservice_delete_tag, and upservice_unassign_tag.
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 attaching tags to the listed entities, but does not explicitly mention when to avoid using it or point to alternatives (e.g., upservice_unassign_tag for removal). However, the verb 'assign' and the sibling names provide clear context, so it's adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or remove multiple links between a directory record and other entities (tasks, projects, orders, etc.) in one call.
Args: params (BulkUpdateRelationsInput): record_id (int), relations (list of {rel_type, relation_ids, is_delete})
Returns: str: JSON confirmation of the applied relation changes.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's mention of adding/removing aligns. The description adds that the return is a JSON confirmation string, but does not disclose potential side effects, requirement of permissions, or non-idempotent behavior 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?
The description is concise with two sentences plus an args list. It is front-loaded with purpose and includes the return type. Could be slightly more structured, but it is efficient with 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 the complexity of the nested input and the presence of an output schema, the description covers the essential behavior (adding/removing links) and return type. It does not detail validation or error handling, but the schema fills gaps, making it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the top-level param, but the schema itself contains detailed descriptions for all nested fields. The description summarizes the args (record_id, relations) but does not add new meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: adding or removing multiple links between a directory record and other entities. It specifies the verb 'Add or remove multiple links' and the resource 'directory record and other entities', which differentiates it from sibling tools that focus on single updates or queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool over alternatives, such as single-relation update tools or listing tools. The description does not mention prerequisites, context, 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.
Mark a project as completed.
Args: params (ProjectIdInput): project_id (int)
Returns: str: JSON of the updated project record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says it marks as completed and returns a JSON of the updated record. This adds behavioral context beyond annotations (idempotent, non-destructive) by specifying the state change and return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: a single sentence for purpose, then clear args/returns format. Every part is essential and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, clear output), the description covers the core functionality. However, it omits error conditions or prerequisites (e.g., project must exist). Annotations and output schema provide additional context.
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% per context, but the schema actually includes a description for project_id. The tool description only restates the parameter name and type, adding no extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Mark a project as completed', using a specific verb and resource. It distinguishes itself from siblings like create, update, delete, and get 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, e.g., when to complete vs update a project. No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a sprint as completed.
Args: params (SprintIdInput): sprint_id (int)
Returns: str: JSON of the updated sprint.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds minimal behavioral context (returns updated sprint), but does not contradict 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 very short and front-loaded, with no wasted text. However, it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given single parameter, existing output schema, and annotations, the description is adequate but lacks details on what completing a sprint entails (e.g., effect on tasks, dates). Missing guidance for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'sprint_id' is described in the schema as 'The Upservice sprint ID'. The description's 'Args' section restates this without adding new meaning. Schema coverage is 0% per context, but the schema already provides adequate description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Mark a sprint as completed' uses a specific verb and noun, clearly identifying the tool's purpose. It distinguishes from sibling tools like 'activate_sprint' or 'delete_sprint'.
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, such as when a sprint should be completed versus activated or updated. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new custom directory (reference catalog).
Args: params (CreateDirectoryInput): title, manager_id (int), parent_id (optional int)
Returns: str: JSON of the created directory.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is a write operation (readOnlyHint=false) and not destructive. The description adds no further context about side effects, permissions, or other behavioral traits beyond the creation act.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences and a parameter summary. No redundant information, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter with nested object) and the presence of schema and output schema, the description is mostly adequate. Missing some context on error conditions or return values beyond 'JSON of the created directory'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already contains descriptions for all parameters. The description repeats parameter names and types briefly but adds minimal new information beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new custom directory (reference catalog). The verb 'create' and resource 'directory' are specific, and the name distinguishes it from siblings like update and delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, scenarios, 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.
Create a new record within a directory (e.g. an asset or contact entry).
Args: params (CreateDirectoryRecordInput): title, category (directory ID), responsible (employee ID), description (optional), inventory_number (optional), extra_fields (optional dict)
Returns: str: JSON of the created record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write operation (readOnlyHint=false) and non-destructive. Description adds return format and that it creates a record, but no details on side effects, authorization, or error handling.
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 clean sentences plus an args/returns section. Purpose first, then parameter list, then return value. No 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?
Covers purpose, required and optional params, and return type. Lacks explanation of extra_fields usage but is sufficient for a moderately complex create tool with output schema.
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 descriptions already explain each parameter (e.g., 'Record title', 'Directory ID'). The description lists parameters with brief type hints but adds little beyond schema. Baseline 3 due to high schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (create) and resource (directory record) with examples (asset or contact entry). Distinguishes from sibling tools like upservice_create_directory and upservice_create_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Does not mention alternatives or prerequisites, but context implies it's for creating new records in an existing directory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new external/inbound message (e.g. from an external channel integration).
Args: params (SendMessageInput): content (str), message_id (optional UUID str), mentions (optional)
Returns: str: JSON of the created message.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. Description adds minimal behavioral context beyond stating it creates a message. Does not disclose required permissions, rate limits, or side effects. Does not contradict 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?
Description is front-loaded with the main purpose sentence and includes Args/Returns for structure. The Args section is redundant with the schema but not overly verbose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details about the return value (only says 'JSON of the created message' without structure). No context about which external channel or how the message is routed. For a creation tool with output schema=true (though not provided here), more explanation 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?
Description lists subfields (content, message_id, mentions) but only minimally. Schema has 0% coverage for the top-level 'params' property, so description should provide more detail. However, the nested schema descriptions are rich, partially compensating. The description adds little semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Create a new external/inbound message' with a specific verb and resource. The example 'from an external channel integration' adds context, but does not explicitly distinguish from sibling tools like upservice_send_channel_message or upservice_send_chat_message.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for external/inbound messages, but no explicit guidance on when to use this tool vs alternatives. No when-not-to-use or alternative tool names mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project in Upservice.
Args: params (CreateProjectInput): - title (str): Project title - managers (List[int]): Employee IDs to assign as project managers - members (List[int]): Employee IDs to assign as project members - extra_fields (Optional[dict]): Extra raw JSON fields to merge into the body
Returns: str: JSON of the created project record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the creation behavior is implied. The description adds no additional behavioral context (e.g., permissions needed, side effects, or rate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured as a docstring with Args and Returns sections. It is concise but the parameter listing is redundant given the schema. The Returns section adds value by specifying the output format.
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 creation tool, the description covers the action, parameters, and return type. It lacks usage guidelines but is otherwise complete given the presence of an output schema (though not shown). The complexity is low, so a 4 is appropriate.
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 description lists parameters with types and brief descriptions, repeating much of the schema's own parameter descriptions. However, the extra_fields parameter gets a slightly clearer explanation ('Extra raw JSON fields to merge into the body') compared to the schema's description. Schema coverage is 0% in the description but the schema has its own descriptions, so baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new project in Upservice,' which is a specific verb-resource pair. It distinguishes well from sibling tools like upservice_update_project and upservice_delete_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as upservice_complete_project or upservice_update_project. No prerequisites or context for usage are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new sprint under a project.
Args: params (CreateSprintInput): title, project (int), date_start (YYYY-MM-DD), date_end (YYYY-MM-DD), extra_fields (optional dict)
Returns: str: JSON of the created sprint.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a write operation. The description adds the return format (JSON string of created sprint), providing useful context beyond 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 concise with three clear sections: purpose, args, returns. Every sentence is necessary and well-structured without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, annotations, and presence of an output schema, the description covers key aspects. It lacks mention of error handling or prerequisites like project existence, but is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains descriptions for all required and optional parameters (100% coverage). The description lists parameters but does not add significant new meaning beyond summarizing schema details.
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 'Create a new sprint under a project' with a specific verb (create) and resource (sprint), distinguishing it from siblings like update, delete, list, and get sprints.
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 creating sprints but lacks explicit guidance on when to use this tool versus other sprint-related tools (e.g., update, delete, activate). No when-not or alternative conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tag definition.
Args: params (CreateTagInput): name (str), color (optional str), type (optional: text|number|address|date|richard)
Returns: str: JSON of the created tag, including its UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, etc. The description adds no further behavioral details (e.g., side effects, permissions, idempotency). It does not contradict 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 reasonably concise, using standard Args/Returns format. No unnecessary words, though could be slightly tighter.
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 creation tool, the description covers purpose and return format. However, it omits important context like uniqueness constraints, error handling, or required permissions, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all parameters with descriptions and enum for type. The description merely summarizes these, adding little new meaning. With high schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new tag definition' with a specific verb and resource. It effectively distinguishes from sibling tools like upservice_update_tag, upservice_delete_tag, and upservice_list_tags.
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. Missing context like prerequisite for tag assignment or that duplicate names may be rejected. The description fails to help the agent choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new task (or meeting/agreement/ticket, depending on kind).
Args: params (CreateTaskInput): title, kind, description, project, sprint, responsible, responsible_departments, estimation (minutes), date_start, date_end, file_list, mentions, extra_fields
Returns: str: JSON of the created task record, including its ID.
Examples: - "Create a task 'Fix login bug' in project 42, due 2026-08-01" -> title="Fix login bug", project=42, date_end="2026-08-01T00:00:00Z" - "Create a task and mention Ivan (employee_id 115768) in the description" -> description="cc {{115768}}", mentions=[{"employee_id": 115768, "display_name": "Ivan Ivanov"}]
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, etc. Description adds that the tool returns JSON with ID, but does not disclose side effects, idempotency, or failure behavior. Acceptable but not rich.
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?
Concise: one-line summary, parameter list, return type, and two examples. No redundant sentences. Information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key parameters and usage via examples. No output schema, but return type is stated. Lacks error conditions or required permissions, but overall sufficient for the tool's complexity.
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 description lists all parameters and provides concrete examples, including mention syntax. Schema already has descriptions, but the examples add practical meaning. Coverage signal is 0% but schema actually has descriptions; still, the description adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a new task (or meeting/agreement/ticket, depending on `kind`)' with a specific verb and resource. Examples further clarify usage. Distinct from sibling tools like upservice_update_task or upservice_delete_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Siblings include other creation tools (upservice_create_project, upservice_create_sprint), but the description does not differentiate contexts. Usage is implied by the examples.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a directory (and, depending on account settings, its records). Destructive operation.
Args: params (DirectoryIdInput): directory_id (int)
Returns: str: JSON confirmation, or "Error: ..." on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond annotations: notes that records may also be deleted depending on account settings, and marks it as destructive. Annotations already indicate destructiveHint=true, but description elaborates on side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three sentences covering purpose, args, and returns. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequately covers the tool's behavior for a simple destructive operation. Mentions return format and error case. Lacks prerequisites or permission requirements, but annotations compensate partially.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers the single parameter (directory_id) with description. The description repeats the parameter info without adding new semantic meaning or examples.
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 deletes a directory permanently, and mentions possible record deletion depending on account settings. Distinguishes from sibling tools like upservice_delete_directory_record by focusing on directories.
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?
Describes the tool as destructive but does not provide explicit guidance on when to use it versus alternatives (e.g., upservice_delete_directory_record). No when-not-to-use or contextual suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a directory record. Destructive operation.
Args: params (RecordIdInput): record_id (int)
Returns: str: JSON confirmation, or "Error: ..." on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds 'Permanently delete' and return type (JSON confirmation or error), which provide minimal extra 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?
The description is concise with a clear front-loaded sentence. The docstring format adds structure without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description covers the action and return type adequately. However, it omits details about error cases, idempotency (despite annotation), and prerequisites.
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% per context signal, but the parameter record_id has a description in the schema. The tool description merely restates the parameter name and type ('record_id (int)') without adding meaningful context or explanation.
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 'Permanently delete a directory record' with a verb and resource, and the sibling tools include both delete_directory and delete_directory_record, so it distinguishes itself effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, such as upservice_delete_directory. The 'destructive operation' warning implies caution but does not compare to other deletion tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a project. This is a destructive operation and cannot be undone.
Args: params (ProjectIdInput): project_id (int)
Returns: str: JSON confirmation, or "Error: ..." on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint: true and idempotentHint: true; the description reinforces this by stating 'cannot be undone', adding the irreversibility 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?
The description is extremely concise, with a single sentence for purpose and a terse args/returns section, all front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential destruction semantics and returns; additional context about prerequisites or state constraints could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description merely restates the schema ('params (ProjectIdInput): project_id (int)') without adding any additional meaning or usage guidance, and schema coverage is 0%.
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 'Permanently delete a project', which is a specific verb and resource, and distinguishes it from sibling tools like delete_task or delete_sprint.
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 explicitly warns that this is a destructive and irreversible operation, but does not contrast it with alternatives like 'complete_project' or specify when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a sprint. This is a destructive operation.
Args: params (SprintIdInput): sprint_id (int)
Returns: str: JSON confirmation, or "Error: ..." on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and readOnlyHint=false. The description adds the explicit statement of permanence ('Permanently delete') and confirms the return value as a JSON confirmation or error message, which supplements 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 extremely concise: two lines of prose plus a structured args/returns section. Every sentence serves a purpose: stating the action, highlighting destructiveness, and specifying parameters and output format.
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 simplicity of the tool (single required parameter, no output schema needed beyond a string), the description covers the essential aspects: action, permanence, input, and return format. It could be slightly improved by noting that the sprint should not be active, but it is adequate.
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 only restates 'sprint_id (int)' without adding meaningful usage context or constraints beyond what the schema already provides (type and required status). The schema itself has a description for sprint_id, so the description adds minimal value.
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 'Permanently delete a sprint' with a specific verb and resource. The tool name and description effectively distinguish it from sibling delete tools (e.g., upservice_delete_project, upservice_delete_task) by focusing on the sprint 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?
No explicit guidance on when to use or avoid this tool. No mention of prerequisites, alternatives, or situations where deletion might be inappropriate (e.g., active sprint). The description implies usage for deleting a sprint but lacks context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a tag definition (removing it from all entities it was applied to).
Args: params (UpdateTagInput): only tag_id is used (UUID str)
Returns: str: JSON confirmation, or "Error: ..." on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds specifics beyond annotations: permanence, cascading removal, ignoring unused params, and return format. Annotations already indicate destructive and idempotent, but description provides valuable 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?
Concise paragraph with clear Args/Returns structure. Minor room for trimming but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple delete operation given output schema exists. Lacks explicit note about tag existence prerequisite but not critical.
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?
Clarifies that only tag_id is used despite schema having other fields, and states it's a UUID string. Compensates for potential confusion from unused parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a tag definition permanently and removes it from all entities, distinguishing it from sibling tools like upservice_unassign_tag.
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 vs alternatives such as upservice_unassign_tag. Missing context for expected usage conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a task. This is a destructive operation and cannot be undone.
Args: params (TaskIdInput): task_id (int)
Returns: str: JSON confirmation, or "Error: ..." on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the description reinforces the destructive hint by noting permanence, it contradicts the idempotentHint annotation: deleting an already-deleted task would return an error, not be idempotent, as implied by the return format.
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 brief, front-loaded with the key statement, and includes a structured docstring for arguments and returns with 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 delete tool, the description covers purpose, irreversibility, and return format. However, the idempotency contradiction and openWorldHint leave ambiguity about side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes a description for 'task_id', so the description adds no new meaning. It merely repeats the parameter name and type.
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 'Permanently delete a task', specifying action and resource. It distinguishes from sibling delete tools targeting 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?
The description warns about destructive and irreversible nature, providing strong context for when to use. However, it does not explicitly exclude alternative tools or specify prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the acquaintance sheet (who has read/acknowledged) for a task of kind 'acquaintance'.
Args: params (TaskIdInput): task_id (int)
Returns: str: JSON with acknowledgement status per employee.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds context that the output is a JSON string with acknowledgement status per employee, which is useful beyond 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 minimal—two sentences and a parameter line—with no fluff. Every part contributes to understanding the tool's function and input.
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 an output schema, the description covers the key aspects: purpose, input, and output type. The output description is generic but sufficient given the presence of an output schema.
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%, yet the description does not provide any additional meaning beyond what the schema already states (task_id is an integer). It simply reiterates the parameter structure without explaining its context or 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 verb 'Get' and the resource 'acquaintance sheet', specifying it is for a task of kind 'acquaintance'. This distinguishes it from sibling tools like upservice_get_task or upservice_get_agreement_sheet, which serve different purposes.
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 is for 'acquaintance' tasks, but provides no explicit guidance on when to use it vs. alternatives (e.g., upservice_get_agreement_sheet) or when not to use it. The context of task type is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the agreement sheet (approval status and attachments) for a task.
Args: params (TaskIdInput): task_id (int)
Returns: str: JSON with status and attachments for the agreement.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description complements this by specifying the return format (JSON with status and attachments), which is not obvious from annotations. No contradictions are present.
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 concise, with a clear purpose stated upfront. The Args/Returns section is efficient, though somewhat formulaic. Every sentence is necessary and 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?
Despite the lack of an explicit output schema, the description adequately explains the return value. For a simple read-only tool with one parameter, the description covers the essential information. It does not mention error handling, but that is acceptable for a getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the top-level parameter 'params', but the description mentions 'task_id (int)'. The schema itself defines 'task_id' with a description, so the description adds minimal extra meaning. It confirms the parameter structure but does not enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('agreement sheet'), and the context ('for a task'). It distinguishes from sibling tools like 'upservice_get_acquaintance_sheet' and 'upservice_get_agreement_steps' by specifying the exact sheet and including approval status and attachments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need the agreement sheet for a task) but does not explicitly state when not to use it or mention alternative tools. No direct comparison or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the approval/agreement steps and their statuses for a task.
Args: params (TaskIdInput): task_id (int)
Returns: str: JSON list of agreement steps.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds no additional behavioral context beyond listing statuses, which is consistent with a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, with purpose, args, and return type in a few lines. No unnecessary information, though could be better formatted.
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 read tool with annotations covering safety, description is adequate. Mentions return type as JSON list. Output schema exists but not shown; description covers basics.
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?
Description mentions 'task_id (int)' but schema already defines task_id with type and description. Schema coverage is 0% as per context, meaning description doesn't add significant value 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 'List the approval/agreement steps and their statuses for a task,' specifying verb, resource, and scope. It distinguishes from sibling tools like upservice_task_agreement_action, which performs actions on steps.
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. Does not mention when not to use or provide context for choosing over similar tools like upservice_task_agreement_action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a fresh, time-limited download URL for a file/attachment scoped to an external channel.
Args: params (ChannelFileIdInput): channel_unique_identifier (str), file_id (str)
Returns: str: JSON containing the file's download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: the URL is 'fresh' (newly generated) and 'time-limited' (expires), which contradicts no annotation. 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 concise, front-loading the main purpose in the first sentence, followed by a structured Args/Returns section. It is slightly verbose with the 'Returns' line but overall 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?
The description covers the essential aspect (fresh, time-limited channel-scoped URL) and the return format. With a full input schema and output schema, it is sufficiently complete for a simple read operation. Minor: could clarify that the file must belong to the given channel.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides good descriptions for both parameters ('file_id' and 'channel_unique_identifier'). The tool description merely restates their names and types without adding new meaning, so baseline 3 is appropriate given high schema coverage (100%).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets a fresh, time-limited download URL for a file scoped to an external channel. The verb 'get' and specific resource 'channel file download URL' make the purpose precise and distinct from sibling tools like upservice_get_file_url, which may handle general file URLs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, such as upservice_get_file_url for non-channel files or upservice_get_task_attachments for task attachments. The channel scope is implied but not compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get messages for a specific chat room within a specific channel.
Args: params (GetChatMessagesInput): channel_unique_identifier (str), room_uuid (str), limit, offset
Returns: str: JSON list of messages in that room.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description is not required to disclose read-only behavior. It adds return type ('JSON list of messages') but does not elaborate on pagination or other side effects beyond what the schema provides.
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 concise (three sentences) and follows a clear structure: purpose, Args, Returns. No extraneous information, though it could be slightly more front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the good annotations and schema coverage, the description is adequate for a read operation but lacks usage guidance relative to sibling tools. It does not explain prerequisites or output structure beyond mentioning a JSON list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for each parameter (channel_unique_identifier, room_uuid, limit, offset) with details on defaults and constraints. The description merely lists parameter names without adding new meaning, so it is redundant.
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 'Get messages for a specific chat room within a specific channel,' specifying the verb and resource scope. However, it does not distinguish from sibling tool 'upservice_list_chat_messages', which could cause confusion.
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 vs alternatives (e.g., list_chat_messages, send_chat_message). The description only states what the tool does without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single directory by ID.
Args: params (DirectoryIdInput): directory_id (int)
Returns: str: JSON of the directory record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds the return format (JSON string of the directory record), which provides useful context 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?
The description is extremely concise: one sentence for purpose, then clearly formatted argument and return sections. No filler or redundant information. Front-loaded with the core 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?
For a simple get-by-ID tool with one parameter and an existing output schema, the description covers all necessary aspects: what the tool does, what input is required, and what output to expect. No gaps remain.
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%, but the parameter 'directory_id' is already well-documented in the input schema with its own description ('The Upservice directory ID'). The description merely repeats the parameter name and type without adding new semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve a single directory by ID,' which is a specific verb+resource combination. It distinguishes from sibling tools like 'list_directories' that return multiple records, and from mutation 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?
No explicit guidance on when to use this tool versus alternatives such as 'upservice_list_directories' or 'upservice_get_directory_record.' The usage is implied by the name and description, but not spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single directory record by ID.
Args: params (RecordIdInput): record_id (int)
Returns: str: JSON of the record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds only the return format (JSON of the record). This is minimal but consistent with annotations. No additional behavioral traits are disclosed beyond 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?
The description is short and front-loaded with the purpose. However, the 'Args' and 'Returns' lines are somewhat redundant given the schema and add no new information. Overall, it is efficiently sized but could be slightly tighter.
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 read-only tool with one parameter and no output schema, the description lacks details like error behavior (e.g., record not found), exact return format, or required permissions. Given the low schema coverage, more is needed to fully guide the assistant.
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% per context, so the description should compensate. It only mentions 'record_id (int)' without adding meaning beyond the schema's own description ('The Upservice directory record ID') or explaining constraints (e.g., required, positive integer).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve a single directory record by ID.' It uses a specific verb (retrieve) and resource (directory record), and distinguishes from sibling tools like upservice_list_directory_records (which returns multiple) and upservice_get_directory (which retrieves a directory itself).
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 specific record by ID, but it does not explicitly provide when to use this tool versus alternatives (e.g., upservice_list_directory_records for multiple records). No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a fresh, time-limited download URL for a file/attachment.
Args: params (FileIdInput): file_id (str)
Returns: str: JSON containing the file's download URL.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by noting the URL is 'fresh' and 'time-limited', disclosing expiration behavior. Annotations already indicate readOnlyHint and idempotentHint, which are consistent. 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 extremely concise with two sentences: the first states the purpose, the second outlines args/returns. Front-loaded and 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 no enums, the description covers the purpose, return type, and key behavioral trait (time-limited). Annotations provide safety info. Could mention the URL format or expiration duration, but it's largely sufficient.
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%, meaning the description adds no parameter meaning beyond what the schema provides. The description merely restates 'file_id (str)' without elaboration, failing to compensate for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('download URL for a file/attachment'), specifying 'fresh, time-limited'. However, it does not distinguish from similar sibling tools like upservice_get_channel_file_url, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There are no explicit context cues, exclusions, or references to sibling tools, leaving the agent to infer usage without support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single project by ID.
Args: params (ProjectIdInput): project_id (int)
Returns: str: JSON of the project record, or "Error: Resource not found (404)" if it doesn't exist.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the return format (JSON string or error) and the exact error message, which is valuable 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?
The description is extremely concise: two sentences plus a structured Args/Returns block. No unnecessary words, and information is front-loaded, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with annotations covering safety and idempotency, this description is complete. It specifies the required parameter, the return type (JSON), and the error case (404). 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?
Despite the context signal indicating 0% schema description coverage, the schema actually includes a description for project_id. The tool description merely restates the parameter name and type ('project_id (int)'), adding no new meaning. It does not compensate for any missing schema details.
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: 'Retrieve a single project by ID.' It distinguishes from sibling tools like upservice_list_projects (list) and upservice_get_sprint (get by ID for a different entity), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use: when you have a specific project ID. It does not explicitly contrast with list_projects or other get tools, but the purpose is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single sprint by ID.
Args: params (SprintIdInput): sprint_id (int)
Returns: str: JSON of the sprint record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, making the safety profile clear. The description adds no additional behavioral context (e.g., error handling for missing IDs, return format details beyond 'JSON of the sprint record'), so it fails to enhance transparency 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?
The description is short but includes a Python docstring format (Args/Returns) that is unnecessary for MCP and adds clutter. It could be more direct without sacrificing clarity.
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, read-only), the description, combined with the annotations and output schema (present but not shown), provides adequate context. It explains the input and return value, though error scenarios are omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines a single required integer parameter 'sprint_id' with a description. The tool description repeats 'sprint_id (int)' without adding any new meaning, such as valid range, source, or behavioral implications. With schema description coverage at 0% for the top-level 'params' property, the description should compensate but does not.
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 starts with 'Retrieve a single sprint by ID,' clearly stating the verb (retrieve) and resource (sprint) with a specific identifier. This immediately distinguishes it from sibling tools like upservice_list_sprints (list multiple) and upservice_create_sprint (create).
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 is provided on when to use this tool versus alternatives. While the tool's purpose is straightforward (get a sprint by ID), the presence of upservice_list_sprints for batch retrieval suggests that usage guidance could be helpful but is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve full details for a single task by ID.
Args: params (TaskIdInput): task_id (int)
Returns: str: JSON of the task record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, fully covering safety. The description adds that it returns 'full details' as JSON, but no additional behavioral context (e.g., no mention of authentication, rate limits, or side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two short sentences plus structured Args/Returns. Front-loaded with the 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 read tool with full annotations and an output schema, the description adequately covers what the tool does and returns. No mention of error cases or prerequisites, but these are minor given the tool's 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?
Only one parameter (task_id) with a clear description in the schema ('The Upservice task ID'). The tool description repeats 'task_id (int)' but adds no new meaning beyond the schema, which already has coverage. Context indicates 0% schema description coverage, which may be a metric error, but the dimension is scored based on actual added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve full details for a single task by ID.' This uses a specific verb (Retrieve) and resource (task details), distinguishing it from sibling tools like list_tasks, update_task, and delete_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as upservice_list_tasks or other get tools. The agent must infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List file attachments on a task.
Args: params (TaskIdInput): task_id (int)
Returns: str: JSON list of attachments (id, filename, url, etc. - use upservice_get_file_url for a fresh download link).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details like returning a JSON list of attachments with fields (id, filename, url, etc.) and notes that a fresh download link requires another tool, which is informative 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?
The description is extremely concise with no wasted words: two sentences, front-loaded with purpose, then structured args/returns. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and comprehensive annotations, the description covers return format and a related tool. The presence of an output schema further reduces the need for return value 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?
The description restates the parameter 'task_id (int)' that is already fully defined in the input schema. With 0% schema description coverage, the description does not add significant semantic value beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List file attachments on a task' with a specific verb and resource. It distinguishes from siblings like upservice_get_file_url by mentioning it in the returns section, helping the agent differentiate between listing and downloading.
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 that this tool lists attachments and explicitly directs the agent to use upservice_get_file_url for a fresh download link. While it doesn't list when not to use, the alternative is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the co-responsible employees assigned to a task.
Args: params (TaskIdInput): task_id (int)
Returns: str: JSON list of co-responsible employees.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive. Description adds minimal behavioral context by specifying return type (JSON list). 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?
Extremely concise: one sentence for purpose, then structured Args/Returns. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description covers the main points. Lacks edge cases but sufficient for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% according to context, yet the description only repeats the parameter name and type without adding semantic meaning beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists co-responsible employees for a task, using specific verb and resource. Distinguishes from sibling tools like upservice_get_task.
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 versus alternatives. Only states the function, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load messages from one or more Upservice chat rooms.
Args: params (ListChatMessagesInput): chat_uuids (required list), channel_id (required), limit, offset, thread_ids, language, sender_id, message_kind (all optional)
Returns: str: JSON list of messages.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description does not contradict these and adds minimal context (returns JSON list). No additional behavioral traits beyond annotations are disclosed.
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 concise and uses a clear docstring format with Args and Returns sections. It is appropriately sized and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of multiple chat-related sibling tools and the lack of an output schema, the description does not fully specify the return structure or usage context. The output is described only as a JSON string, which may be insufficient for complex usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description reiterates parameter names and required/optional status, but the input schema already provides detailed descriptions for each parameter. With high schema coverage, the description adds no substantial meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool loads messages from Upservice chat rooms, specifying the resource and action. However, it does not differentiate from the sibling tool `upservice_get_chat_messages`, which may have similar functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists required and optional parameters but provides no guidance on when to use this tool versus alternatives like `upservice_get_chat_messages`. No explicit context or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List custom directories (reference catalogs, e.g. assets, contacts) defined in the account.
Note: this endpoint has no pagination in the Upservice API; it returns all matching directories.
Args: params (ListDirectoriesInput): parent, search, id, manager (all optional)
Returns: str: JSON list of directories.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 that there is no pagination and it returns all directories, which is useful but limited. No mention of rate limits, errors, or authentication.
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 concise with two short paragraphs and clear headings for Args and Returns. It is front-loaded with the purpose. However, it could be slightly more structured with bullet points.
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 annotations and output schema, the description covers purpose, behavior (no pagination), and return type. It is adequate for a simple list tool, though it omits error handling or edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description simply lists parameter names (parent, search, id, manager) and notes they are optional, which adds no meaning beyond the input schema. The schema already describes each parameter fully, so the description provides no additional semantics.
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 custom directories (reference catalogs) defined in the account, with examples like assets, contacts. This distinguishes it from sibling tools like get_directory (single directory) or list_directory_records.
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 behavioral context (no pagination) but does not explicitly guide when to use this tool versus alternatives. No mention of when not to use it, making it adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the entities (tasks, orders, projects, etc.) linked/related to a directory record.
Args: params (RecordIdInput): record_id (int)
Returns: str: JSON list of related entities, grouped by relation type.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that the return is a JSON list grouped by relation type, offering some behavioral context beyond annotations but not addressing pagination, limits, or performance.
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 exceptionally concise, using a single sentence for purpose and a clear Args/Returns structure. No redundant information is present.
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 (one parameter) and the presence of an output schema, the description covers the core functionality. It explains the return format (JSON list grouped by relation type). However, it could be improved by noting possible relation types or error conditions.
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 description restates the single parameter 'record_id' with its type and a brief description, but adds no additional semantics like constraints, examples, or format beyond what the schema provides. With 0% schema coverage, more enrichment was expected.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List') and resource ('entities linked/related to a directory record'), with explicit examples (tasks, orders, projects). It is specific and distinct from sibling tools that focus on single entities or different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as upservice_list_directory_records or other relation-related tools. The description does not mention context, prerequisites, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List records within directories, optionally filtered to one or more directories.
Args: params (ListDirectoryRecordsInput): limit, offset, category, responsible, creator, search, id, tags_ids, tags_condition, date_end_gte/lte, is_subscribed (all optional)
Returns: str: JSON list of directory records.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, indicating a safe read operation. The description adds that it returns a JSON list, which is minimally helpful. No contradiction with 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 short and front-loaded with the action. The parameter list is formatted clearly. Could be slightly more concise, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description sufficiently covers the tool's behavior. It mentions the return type and available filters. Pagination hints are present in the parameter list but not explicitly described, which is acceptable.
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 description lists parameter names but provides no details beyond what the input schema already documents. Schema description coverage is 0%, but the schema itself has descriptions for each property. The description adds marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'directory records', with scope 'within directories' and filtering by directory. It differentiates from siblings like 'upservice_get_directory_record' (single record) and 'upservice_list_directories' (list directories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (listing with filters) but does not explicitly state when not to use or compare with alternatives. The agent must infer from sibling names that 'upservice_get_directory_record' is for a single record.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List employees in the Upservice account.
Args: params (ListEmployeesInput): - limit (Optional[int]): Page size, 1-100 (default 25) - offset (Optional[int]): Items to skip for pagination (default 0)
Returns: str: JSON array/object of employees as returned by the Upservice API (fields typically include id, first_name, last_name, email, position, department).
Error Handling: Returns "Error: ..." with an actionable message on failure (see error codes below).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds error handling details (returns 'Error: ...' with actionable message) and return format (JSON with typical fields), going 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?
Description is concise with clear sections (Args, Returns, Error Handling). No redundant information; every sentence serves a 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 (pagination only), the description fully covers usage, parameters, return format, and error handling. Output schema exists, so return details are sufficient.
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?
Description compensates for 0% schema coverage by providing default values (limit=25, offset=0), valid ranges (1-100, 0+), and field examples. This adds practical meaning beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists employees in the Upservice account. The verb 'list' and resource 'employees' are specific and distinguish from other list tools (e.g., list_projects, 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?
No explicit guidance on when to use this tool versus alternatives like upservice_get_* or other list tools. The pagination parameters imply its use for large datasets, but no mention of 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 projects in the Upservice account.
Args: params (ListProjectsInput): limit (1-100, default 25), offset (default 0), status, tags_condition, tags_ids
Returns: str: JSON list of projects (id, title, managers, members, completed, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is clear. The description adds value by specifying the return format (JSON list with fields) and pagination behavior (limit 1-100, default 25; offset default 0), going beyond 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?
The description is a well-structured docstring with Args and Returns sections. The main sentence is concise, but the parameter list is somewhat redundant given the schema. It earns a 4 for clarity and front-loading of key 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 rich annotations (readOnly, idempotent, openWorld) and the presence of an output schema, the description adequately covers the tool's behavior. It mentions return format and pagination, though it could clarify edge cases like empty results or unavailable fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats parameter names and defaults already present in the schema (which has descriptions for each sub-parameter). Since schema description coverage is high (each parameter has a schema description), the description adds marginal value by summarizing them but does not clarify nuances or provide examples.
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 in the Upservice account' with a specific verb and resource. It distinguishes from sibling tools like upservice_get_project (single) or upservice_create_project, leaving no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing projects with pagination and filter options but does not explicitly state when to use this tool versus alternatives (e.g., upservice_get_project for a single project) or when not to use it. Basic guidance is present through parameter descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sprints, optionally filtered by project.
Args: params (ListSprintsInput): limit, offset, project (optional list of IDs), status (optional list), is_lag (optional bool)
Returns: str: JSON list of sprints.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructiveHint, covering the safety profile. The description adds minimal behavioral context beyond stating it returns a JSON list. No mention of pagination behavior, rate limits, or data freshness is provided.
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 concise, front-loading the purpose. However, the Args list largely duplicates information already present in the input schema, which could be considered redundant. Still, it is well-structured and brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the readOnly, idempotent nature and the presence of an output schema (though minimal), the description is adequate. However, it lacks details on pagination behavior, such as whether offset/limit provide a complete list or require multiple calls. Completeness is minimal but not inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains detailed descriptions for each parameter (e.g., 'Page size (max 100)', 'Filter by sprint status(es)'). The description in the docstring summarizes these but adds no new meaning beyond what the schema provides. Since schema coverage is effectively high, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List sprints, optionally filtered by project.' This is a specific verb+resource combination. It is distinguishable from sibling tools like upservice_get_sprint (single sprint) and upservice_create_sprint (creation).
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 does not provide any guidance on when to use this tool versus alternatives like upservice_get_sprint or other list tools. No when-to-use, when-not-to-use, or comparator information is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags defined in the Upservice account, optionally filtered by a search query.
Args: params (ListTagsInput): limit, offset, query (optional str)
Returns: str: JSON list of tags (id, name, color, type).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint false) already convey safety. Description adds return format (JSON list with id, name, color, type) and mentions pagination parameters, providing useful 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?
Description is brief and front-loaded: first sentence states purpose, then compactly lists arguments and return type. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity, full schema coverage, and clear annotations, the description adequately covers all aspects needed for correct tool invocation and understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides full descriptions for each parameter (limit, offset, query) with ranges and defaults. Description merely lists parameter names without adding new semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists tags in the Upservice account with optional search filtering. Distinguishes itself from sibling tools like create_tag or delete_tag by explicitly identifying as a list operation.
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 clearly indicates this tool is for listing tags and implies use when you need to view or browse tags. No explicit when-not guidance is given, but the context is clear given sibling tools focus on create/delete/update.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List/search tasks with optional filters for kind, project, author, responsible, date ranges, and tags.
CONFIRMED LIMITATION (verified against the live API, not just the OpenAPI spec): this
endpoint has no status/status_in/is_completed/completed/query filter. Passing any of
those as extra query params is silently ignored server-side (no error, no effect on
results) — status filtering must be done client-side on the returned status field.
There is no workaround on the Upservice API today; this has been reported to Upservice
as a feature request. Until it lands, narrow results with date_end_gte/date_end_lte
(due-date range) plus project/author/responsible BEFORE paginating and filtering
by status client-side — e.g. for "open overdue tasks", pass
date_end_lte=<now, ISO 8601> together with project/responsible to get a small candidate
set, then drop any whose status is completed/cancelled/rejected/deleted. Do not call
this with only author (or no filters) and try to page through everything — accounts
can have 100k+ tasks and completed_at/date filters are the only server-side way to keep
that bounded.
Args: params (ListTasksInput): limit, offset, kind, project, author, responsible, created_at_gte/lte, completed_at_gte/lte, date_start_gte/lte, date_end_gte/lte, tags_ids, tags_condition (all optional except pagination defaults)
Returns: str: JSON list of tasks matching the filters.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that certain query parameters are silently ignored (status, status_in, etc.), which is beyond the annotations. Also confirms the endpoint behavior and provides a workaround. Aligns with annotations (readOnlyHint, etc.).
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?
Well-structured with a clear overview, specific limitation block, and usage advice. Despite length, every sentence adds value. Slightly verbose but appropriately so for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (many optional filters, pagination) and presence of output schema, the description is thoroughly complete. It covers limitations, optimization strategies, and return format, with no obvious gaps.
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 high (100% based on provided schema), so baseline is 3. The description adds value by clarifying the limitation on status filters and recommended usage patterns, going beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'List/search tasks with optional filters...' clearly stating the verb and resource. It distinguishes from sibling tools like upservice_get_task and other list tools by focusing on listing tasks with filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool vs alternatives, including a detailed limitation on status filters, a concrete example for 'open overdue tasks', and warnings against inefficient calls (e.g., with only author). Includes specific recommendations for parameter usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new message directly in a channel (not tied to a specific chat room).
Args: params (SendChannelMessageInput): channel_unique_identifier (str), content (str), message_id, first_name, last_name, email, phone, mentions (all optional), extra_fields (optional dict)
Returns: str: JSON of the created message.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false. The description adds that it returns a JSON of the created message but does not disclose behavioral traits like idempotency implications (though schema mentions message_id for idempotency), auth needs, or side effects. No contradiction with 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 concise with a clear front-loaded purpose sentence. The args listing could be streamlined but is efficient. 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 the moderate complexity (one parameter object with nested properties) and rich schema descriptions, the description is adequate but lacks guidance on prerequisites (e.g., obtaining channel UUID) and error scenarios. The output schema likely covers return structure, so the return description is sufficient.
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 of parameter descriptions is high (all parameters have descriptions), so baseline is 3. The description lists parameter names but adds no meaning beyond the schema, which already includes detailed explanations for content and mentions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new message in a channel, not in a chat room, distinguishing it from the sibling tool upservice_send_chat_message. The verb 'create' and resource 'message in channel' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly distinguishes channel vs chat room but does not explicitly state when to use this tool over alternatives like upservice_send_chat_message. It provides no prerequisites or exclusions, so usage guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message into a specific chat room within a channel.
Args: params (SendChatMessageInput): channel_id (str), room_uuid (str), content (str), message_id (optional), mentions (optional)
Returns: str: JSON of the sent message.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate not readOnly, not idempotent, not destructive. Description confirms 'Send a message' which is consistent but adds no extra behavioral detail (e.g., what happens if room is missing, rate limits, confirmation). Given annotations cover the core safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence purpose plus a structured Args/Returns section. Front-loaded, but the Args section duplicates schema information. Could be more concise by omitting the parameter list and relying on the schema.
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 provides basic purpose and return type, but lacks explanation of prerequisites, edge cases, or integration with other tools. The schema covers mentions in detail, so the description is minimally complete but not thorough for a messaging tool with complex input.
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 description's Args section merely lists parameter names already defined in the input schema with full descriptions. Schema coverage is effectively 100% (despite context signal showing 0%, all parameters have descriptions). The description adds no new semantic meaning; it is redundant.
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 'Send' and the resource 'message into a specific chat room within a channel'. It effectively distinguishes from sibling tools like upservice_send_channel_message by specifying 'chat room', which is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives (e.g., upservice_send_channel_message, upservice_create_external_message). No mention of prerequisites, when not to use, or fallback scenarios. The agent receives no decision-making context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the full set of managers for a project.
Note: this REPLACES the existing manager list, it does not append to it.
Args: params (SetProjectEmployeesInput): project_id (int), employees (List[int], the new full manager list)
Returns: str: JSON confirmation/updated manager list.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations: the replacement behavior and return format. While annotations indicate non-destructive, the description clarifies that previous managers are replaced.
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 concise and well-structured: action sentence, note about replacement, then parameter listing. No extraneous 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?
The description covers the core functionality, replacement behavior, parameters, and return type. It lacks prerequisites or error scenarios but is sufficient for a straightforward tool with output schema.
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 description explains the parameters (project_id and employees list) and adds meaning by stating 'the new full manager list'. Despite schema description coverage potentially low, the description compensates well.
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 'replaces the full set of managers for a project', using a specific verb and resource. It distinguishes from siblings like upservice_set_project_members by focusing on managers.
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 emphasizes that it REPLACES rather than appends, which is a key usage guideline. It does not explicitly mention when to use vs alternatives, but the sibling context suggests it is the only tool for setting managers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the full set of members/guests for a project.
Note: this REPLACES the existing membership list, it does not append to it.
Args: params (SetProjectEmployeesInput): project_id (int), employees (List[int], the new full member list)
Returns: str: JSON confirmation/updated member list.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description discloses the replacement (write) behavior, consistent with annotations (idempotentHint=true, destructiveHint=false). It adds clarity that the operation is a full replacement, not incremental, which is beyond 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?
Three sentences: purpose, behavioral warning, and argument list. No fluff, well-organized, and front-loaded with the key 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?
Covers the essential: purpose, replacement behavior, parameter types, and return type. Annotations provide idempotency and non-destructive hints. Lacks details on error handling or authorization, but acceptable for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with descriptions (e.g., 'Employee IDs (this REPLACES the current set; Upservice requires at least one)'). The description just restates them, adding no new meaning. Baseline 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Replace the full set of members/guests for a project' with a specific verb (Replace) and resource (project members/guests). It distinguishes from sibling tools like upservice_set_project_managers and avoids confusion with append operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly warns 'this REPLACES the existing membership list, it does not append to it', helping the agent understand when to use vs. avoid. No alternatives are mentioned, but the sibling list lacks an append-members tool, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advance an agreement/approval workflow step on a task: progress it, approve it, or reject it.
Args: params (AgreementActionInput): task_id (int), action (progress|approved|rejected), rejection_reason (required if action='rejected'), date_end (optional, used with 'progress')
Returns: str: JSON of the updated agreement state.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates the tool modifies state (advancing a workflow step) and returns the updated state, consistent with non-readOnly annotations. It does not disclose additional behavioral traits such as side effects, reversibility, or idempotency beyond what annotations imply.
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 concise with two sentences, clearly stating purpose and parameter requirements. The use of 'Args:' and 'Returns:' structure is acceptable but slightly verbose, which prevents a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behavior and return value for a tool with a single parameter and an existing output schema. It does not explain the difference between actions (schema covers that) or potential side effects, but is reasonably complete given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all parameters (task_id, action, date_end, rejection_reason). The description echoes these constraints without adding new meaning, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool advances an agreement/approval workflow step on a task, listing specific actions: progress, approve, reject. This clearly identifies the verb and resource, and the three distinct outcomes distinguish it from other task-related 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?
No guidance is provided on when to use this tool versus alternatives like upservice_update_task_status or upservice_get_agreement_steps. There are no prerequisites, context for use, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove (detach) a tag from an entity.
Args: params (AssignTagInput): tag_id (UUID), entity_id (UUID or int), entity_type (enum)
Returns: str: JSON confirmation, or "Error: ..." on failure.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description aligns. It adds the return format (JSON confirmation or error message). However, it does not explain side effects (e.g., whether the tag is deleted or just detached). With annotations present, a score of 3 reflects adequate but not extensive addition.
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 concise with no wasted words, and includes an 'Args' and 'Returns' section for clarity. Although not in markdown, it is well-structured and easy to parse. A slight reduction from 5 because it could be more standardized.
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 schema descriptions, annotations (destructive, readOnly, idempotent), and output schema, the description is complete enough for a simple tool. It covers purpose, parameters, and return value, leaving minimal ambiguity 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?
The input schema already provides descriptions for all three parameters (tag_id, entity_id, entity_type). The description lists these fields but adds no new semantic meaning beyond what the schema provides. Since schema coverage is effectively high (descriptions present), the description adds marginal value.
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 'Remove (detach) a tag from an entity', specifying the verb and resource. It distinguishes from sibling tools like 'upservice_assign_tag' and 'upservice_delete_tag' by explicitly indicating removal vs. assignment or deletion.
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 does not explicitly state when to use this tool versus alternatives, but the name and context imply it is the inverse of 'assign_tag'. No exclusions or prerequisites are provided, so the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a directory's title or manager.
Args: params (UpdateDirectoryInput): directory_id (int), title (optional), manager_id (optional)
Returns: str: JSON of the updated directory.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, idempotent, non-destructive. Description adds only that it returns JSON of updated directory. No further behavioral details (e.g., overwrite behavior, permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: single-line summary, then clear args and returns. No unnecessary words. Well-structured for an agent.
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 input and output adequately. Output schema exists, so return description is sufficient. Lacks error conditions or prerequisites, but overall complete for a simple update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description lists the three parameters and their types, but the schema already provides descriptions. With 0% schema coverage signal (likely misidentified), the description does provide basic parameter info, but no additional semantics beyond what is 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?
Clearly states 'Update a directory's title or manager.' which is a specific verb and resource, and distinguishes from sibling tools like create, get, delete, 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 explicit guidance on when to use this tool vs. alternatives (e.g., bulk_update_directory_relations). The description just states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a directory record's fields.
Only fields you explicitly pass are sent — an omitted field is left unchanged, while an
explicit null (e.g. responsible=null) is sent as-is and clears that field server-side.
Args: params (UpdateDirectoryRecordInput): record_id (int) plus any fields to change, extra_fields for the rest
Returns: str: JSON of the updated record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by explaining that only explicitly passed fields are sent and that explicit null clears fields. Annotations already indicate idempotency, and the description reinforces safe mutation behavior. 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 concise: a single sentence for purpose, one for behavior, and structured Args/Returns sections. No unnecessary words, well-organized.
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 covers the partial update behavior, field handling, and return type. It lacks error cases or permissions, but overall provides sufficient context for an agent to use the tool 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?
Schema description coverage is 0%, so the description must compensate. It mentions record_id and extra_fields, but does not detail other parameters beyond what the schema provides. The partial update behavior is explained, but more explicit parameter semantics would improve the score.
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 'Partially update a directory record's fields,' specifying the action (update), resource (directory record), and partial nature. It distinguishes from sibling tools like upservice_create_directory_record and upservice_delete_directory_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains partial update semantics and field handling (omitted vs. null), providing clear usage guidance. However, it does not explicitly state when not to use this tool or list alternatives, which would raise the score to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing project's fields (e.g. title).
Args: params (UpdateProjectInput): project_id (int), title (optional str), extra_fields (optional dict)
Returns: str: JSON of the updated project record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which the description does not contradict. The description adds return type info ('Returns: str: JSON of the updated project record.') but does not elaborate on side effects, permissions, or error conditions. With annotations present, the added behavioral context is minimal.
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 compact (3 lines) and front-loaded with the purpose. It includes an Args and Returns section, making it easy to scan. However, it could be slightly more structured (e.g., avoiding the code-style 'Args:' format in favor of plain text).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core update functionality and return format, but lacks details on the use of extra_fields for arbitrary field updates, potential validation constraints, or behavior when fields are omitted. Given the tool has a nested input schema and an output schema, the description is adequate but not fully comprehensive.
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 description lists the parameters (project_id, title, extra_fields) with types and optionality, but the input schema already provides detailed descriptions for each property. Since schema_description_coverage is effectively high (schema includes descriptions), the description adds no new semantic value beyond restating schema information.
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 'Update an existing project's fields (e.g. title)', providing a specific verb and resource. It distinguishes from sibling tools like upservice_create_project, upservice_delete_project, and other update tools (e.g., upservice_update_sprint) by specifying 'project'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates this is the general update tool for projects, but does not explicitly guide when to use it versus specialized siblings like upservice_set_project_managers or upservice_complete_project. No prerequisites or exclusions are mentioned, leaving usage context somewhat implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a sprint's title or dates.
Args: params (UpdateSprintInput): sprint_id (int), title/date_start/date_end (all optional), extra_fields (optional dict)
Returns: str: JSON of the updated sprint.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show idempotentHint true and openWorldHint true, but the description does not explain side effects, permissions, or behavior like merging extra_fields. It adds little beyond stating 'Update,' leaving transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: purpose in the first sentence, then args and return summarized. Every sentence adds value, 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?
Includes return type (str JSON) and output schema exists, so completeness is good. However, given openWorldHint, more context on side effects would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for each parameter. The description lists the parameters but adds minimal extra meaning; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a sprint's title or dates,' specifying the verb and resource. It distinguishes from sibling tools like create_sprint, complete_sprint, and delete_sprint, which have different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for updating title and dates, but lacks explicit guidance on when to use versus alternatives (e.g., when to use complete_sprint instead) or conditions like sprint status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing tag's name or color.
Args: params (UpdateTagInput): tag_id (UUID str), name (optional), color (optional)
Returns: str: JSON of the updated tag.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds that it returns JSON of the updated tag, but no additional behavioral traits 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?
Short and to the point, with a structured docstring format. No unnecessary words, but could be slightly more compact.
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 basic operation and return type. Since an output schema exists, the description need not detail return values. Could mention that name and color are optional (implied by defaults). Adequate for a simple update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only lists parameters in a docstring without elaborating on requirements, formats, or constraints beyond what the schema provides. Minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing tag's name or color, using a specific verb and resource. It distinguishes itself from sibling tools like create_tag and delete_tag.
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 vs. alternatives, no prerequisites or context. The description only states what it does, not when it should be chosen.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially update a task's fields (title, description, dates, responsible, etc).
Only fields you provide are changed; omitted fields are left unchanged.
Args: params (UpdateTaskInput): task_id (int) plus any fields to change, mentions (for description), and extra_fields for anything not explicitly modeled
Returns: str: JSON of the updated task record.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds value by explaining that only provided fields are changed and omitted ones remain unchanged, which goes beyond the annotations. No mention of side effects or authorization, but the annotations cover the non-destructive nature.
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 concise with a clear first sentence defining the action, followed by a brief explanation of partial update behavior. The Args and Returns sections are well-structured and not redundant. 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?
Given the tool's complexity (multiple optional fields, partial update) and the presence of a detailed schema and output schema, the description covers the essential behavior. It explains the update semantics and return format. Could optionally mention that date fields are ISO 8601, but that is already in the schema.
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?
Although context indicates 0% schema description coverage, the actual input schema provides detailed descriptions for each parameter. The description adds context for 'mentions' and 'extra_fields' beyond the schema, helping the agent understand their purpose. The listing of fields in the description is beneficial.
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 'Partially update a task's fields' with a specific verb and resource. It lists example fields (title, description, dates, responsible, etc.) and distinguishes from sibling tools like create or delete tasks. The partial update behavior is explicitly emphasized.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the partial update behavior and lists updatable fields but does not explicitly state when to use this tool versus more specific siblings like upservice_update_task_status or upservice_update_task_estimation. Usage context is implied but not clearly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the planned-effort estimate for a task, in minutes.
Args: params (UpdateTaskEstimationInput): task_id (int), estimation (int, minutes)
Returns: str: JSON of the updated task.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent (idempotentHint=true) and non-destructive (destructiveHint=false). Description adds return value info but no additional behavioral traits like permissions, side effects, or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short and front-loaded with purpose. The Args/Returns block is somewhat redundant but not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 required param, simple operation) and presence of output schema, the description adequately covers the tool's function and return type.
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 descriptions already fully define parameters (task_id and estimation). Tool description's Args block merely restates schema info, adding no new semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Set' and specific resource 'planned-effort estimate for a task' in minutes. Distinguishes from sibling tools like upservice_update_task (general update) and upservice_update_task_status (status update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for setting estimation but provides no explicit guidance on when to use versus alternatives, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a task's status (e.g. mark as completed, cancelled, in progress).
Args: params (UpdateTaskStatusInput): task_id (int), status (enum), reason (optional str, needed for cancel/reject)
Returns: str: JSON of the updated task.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false), non-destructive, and idempotent. Description adds return value format and condition for reason parameter, but does not elaborate on side effects or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is very concise, front-loaded with the main action, followed by a clear Args and Returns section. No redundant or unnecessary 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?
Covers input parameters and return format adequately. Lacks details on status transition validation or side effects, but given the tool's simplicity and existing annotations, it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes parameters with details. The description adds a succinct summary and explicitly states reason is needed for cancel/reject, which adds marginal value beyond the schema's 'typically required' phrasing.
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 changes a task's status with examples (completed, cancelled, in progress). It differentiates from siblings like upservice_update_task by focusing on status only, but does not explicitly exclude other update 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?
Provides implicit usage guidance by indicating that reason is needed for cancel/reject statuses. However, it does not explicitly state when to use this tool versus upservice_update_task or other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Log actual effort (worklog) spent on a task, in minutes.
Args: params (UpdateTaskWorklogInput): task_id (int), value (int, minutes of actual effort)
Returns: str: JSON of the updated task/worklog.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, confirming mutation but no destruction. However, the description does not add behavioral context beyond what annotations already convey. It fails to disclose whether the worklog is appended or overwritten, any required permissions, or side effects like changing task status. With annotations present, the description should provide additional behavioral nuance but does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single-sentence summary followed by a structured Args/Returns block. There is no fluff, and every sentence provides necessary information. It is front-loaded with the core purpose, making it easy for an agent to quickly understand the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool is a mutation (write operation) and has an output schema, the description mentions the return type ('JSON of the updated task/worklog') which is adequate. However, it does not explain whether the worklog is appended or replaces existing entries, nor does it describe any constraints such as maximum minutes. For a mutation tool, this missing behavioral detail reduces 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?
The description includes an explicit Args section listing both parameters (task_id, value) and their types, with value described as 'minutes of actual effort'. The input schema also provides descriptions for each parameter. Since the description clarifies the parameters beyond the schema—especially the unit for value—it adds value. Schema coverage is effectively 100% because both parameters have descriptions, so baseline is 3, and the description's extra context pushes it to 4.
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 'Log' and the resource 'actual effort (worklog) spent on a task', distinguishing it from sibling tools like upservice_update_task which handle general task updates. The specific reference to minutes and the inclusion of task_id and value parameters confirm the tool's focused purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as upservice_get_task or upservice_update_task. It does not mention prerequisites (e.g., task must exist), nor does it specify if the worklog is appended or replaced. The description lacks any when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local file to Upservice (e.g. to attach it to a task via its returned file ID).
Args: params (UploadFileInput): file_path (absolute local path)
Returns: str: JSON of the uploaded file record, including its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly and non-destructive. The description adds that the tool uploads a file given an absolute local path, but does not disclose permissions, rate limits, or side effects. No contradiction with 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 three sentences, front-loaded with the purpose. It is clear and efficient, though the parameter description could be omitted since the schema covers it.
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 parameter), annotations, and an output schema (which mentions returned JSON with ID), the description is mostly complete. It explains the return value and the purpose of the file ID, but could mention error cases or file size limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a description for 'file_path' ('Absolute local filesystem path of the file to upload'). The description repeats this in a slightly different wording ('absolute local path'), adding no new semantic value. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('upload a local file to Upservice') with a specific purpose (attach to a task via returned file ID). This distinguishes it from sibling tools like 'upservice_upload_file_to_channel' which uploads to a channel.
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 attaching files to tasks but does not explicitly provide when-to-use/when-not-to-use guidance or compare with alternatives like 'upservice_upload_file_to_channel'. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local file to an external channel in Upservice.
Args: params (UploadFileToChannelInput): channel_unique_identifier (str), file_path (absolute local path)
Returns: str: JSON of the uploaded file record, including its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds return behavior (JSON with ID) but lacks details on file size limits, permission requirements, or error handling.
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 concise, using a structured Args/Returns format with no extraneous text. It could be slightly more efficient but is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers basic purpose, parameters, and return format, but given the complexity of file uploads, it omits details like supported file types, size limits, and authentication. Output schema presence is noted but not elaborated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for both parameters (file_path and channel_unique_identifier). The description repeats this info without adding new semantics, so it meets the baseline but does not exceed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it uploads a local file to an external channel in Upservice. It uses a specific verb and resource, distinguishing it from sibling tools like upservice_upload_file and upservice_send_channel_message, though it could be more explicit about what 'external channel' means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., upservice_upload_file or upservice_get_channel_file_url). There are no prerequisites or context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0upservice_create_external_message2 fields changedInput schema / $defs / MentionInputAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "display_name": {
+ "description": "Display name to show for the mention, e.g. 'Ivan Ivanov'",
+ "title": "Display Name",
+ "type": "string"
+ },
+ "employee_id": {
+ "description": "Employee ID to mention (from upservice_list_employees)",
+ "title": "Employee Id",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "employee_id",
+ "display_name"
+ ],
+ "title": "MentionInput",
+ "type": "object"
+}Input schema / $defs / SendMessageInput / properties / mentionsAdded value: +{
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/MentionInput"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Employees to mention in `content`. Put a `{{employee_id}}` placeholder in the content text for each mention; it will be substituted with the correct @[Name](id) syntax.",
+ "title": "Mentions"
+}upservice_update_directory_record1 field changedInput schema / $defs / UpdateDirectoryRecordInput / properties / responsible / descriptionPrevious value: -"New responsible employee ID. Omit to leave unchanged; use null to clear."New value: +"New responsible employee ID. Omit to leave unchanged; pass null to clear."v0.1.0upservice_activate_sprintupservice_add_tasks_to_sprintupservice_assign_tagupservice_bulk_update_directory_relationsupservice_complete_projectupservice_complete_sprintupservice_create_directoryupservice_create_directory_recordupservice_create_external_messageupservice_create_projectupservice_create_sprintupservice_create_tagupservice_create_taskupservice_delete_directoryupservice_delete_directory_recordupservice_delete_projectupservice_delete_sprintupservice_delete_tagupservice_delete_taskupservice_get_acquaintance_sheetupservice_get_agreement_sheetupservice_get_agreement_stepsupservice_get_channel_file_urlupservice_get_chat_messagesupservice_get_directoryupservice_get_directory_recordupservice_get_file_urlupservice_get_projectupservice_get_sprintupservice_get_taskupservice_get_task_attachmentsupservice_get_task_co_responsiblesupservice_list_chat_messagesupservice_list_directoriesupservice_list_directory_record_relationsupservice_list_directory_recordsupservice_list_employeesupservice_list_projectsupservice_list_sprintsupservice_list_tagsupservice_list_tasksupservice_send_channel_messageupservice_send_chat_messageupservice_set_project_managersupservice_set_project_membersupservice_task_agreement_actionupservice_unassign_tagupservice_update_directoryupservice_update_directory_recordupservice_update_projectupservice_update_sprintupservice_update_tagupservice_update_taskupservice_update_task_estimationupservice_update_task_statusupservice_update_task_worklogupservice_upload_fileupservice_upload_file_to_channelScored across 58 tools
The messaging tools overlap heavily: list_chat_messages vs get_chat_messages are nearly indistinguishable from their descriptions, and create_external_message vs send_channel_message vs send_chat_message blur the boundary between a channel, a room, and an external message. Outside messaging, most task/project/sprint/directory tools are clearly distinct, but the chat subset creates real misselection risk.
Names overwhelmingly follow the upservice_<verb>_<noun> pattern, which is a strong and predictable convention. The main deviations are upservice_task_agreement_action (noun-first instead of verb-first) and the mixed create_/send_ verbs across the message tools, but these are minor against the overall consistency.
58 tools is well past the 50+ threshold and is extreme for a single MCP server, even for a broad project-management API. The agent-facing surface is bloated and would be far more navigable if split into focused servers by domain (tasks, projects, directories, chat).
The server provides solid CRUD coverage for tasks, projects, sprints, tags, directories, and directory records, plus file upload/download and task workflow operations. Notable gaps include no way to discover channels/chat rooms, no remove-tasks-from-sprint operation, and no update/delete for messages, which agents may need to work around.
Manage dillie projects, tasks, and sprints; look up members and search platform documentation.
Read teams, spaces, lists and tasks; create, update and comment on tasks and track time.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
