Skip to main content
Glama
minhtrancmvn

asana-local-mcp

by minhtrancmvn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Asana Local MCP

A local, read-only MCP server for Asana. It exposes exactly six tools that query Asana through the public REST API with a personal access token, and it never sends a POST, PUT, PATCH, or DELETE request. The server does not run a cloud service, does not store a cache or index, and does not implement OAuth, webhooks, or account registration.

Contract at a glance

  • GET-only data plane; no mutation endpoints, no token argument in any tool

  • Six tools: list_projects, search_tasks, get_task, list_task_comments, search_comments, get_attachment

  • Token is read only from the ASANA_ACCESS_TOKEN environment variable

  • Attachment access links stay out of task and comment output by default

  • No local writes: no files, no cache, no index

  • All error messages are sanitized; tokens, headers, and ephemeral URLs never appear in tool output or logs

Requirements

  • Python 3.11 or newer

  • uv (the lockfile is uv.lock)

python3 --version        # 3.11+
uv --version             # install uv first if missing

Related MCP server: asana-mcp

Install and sync

Clone the repository and install all dependencies (including the dev extras used by the test suite):

uv sync --all-extras

Run the full test suite:

uv run pytest -q

Local run options

Unpublished local checkout (this repository)

Launch the server straight from the checkout. In an MCP client config, use uv --directory pointed at the checkout; do not use uvx for an unpublished package — uvx asana-local-mcp only works once the package is published to PyPI or an index:

uv --directory /Users/coffeemug/Programming/asana-local-mcp run asana-local-mcp

Editable install (development)

uv sync --all-extras
uv run asana-local-mcp

Published execution (from PyPI or an index)

uvx asana-local-mcp

All entry points resolve the same console script, asana_local_mcp.server:main, which serves the MCP protocol over stdio.

Authentication

The server reads the access token exclusively from the ASANA_ACCESS_TOKEN environment variable. Never pass the token as a tool argument: no tool accepts one, and a token in any MCP client config is a secret waiting to leak.

  1. Create a personal access token in Asana (Profile > My profile settings > Apps > Personal access tokens). Scope it to attachments:read and the data-access scope your projects need; the attachment tools require attachments:read.

  2. Add it to the environment of your local MCP client configuration only. Never paste the real value into this repository, a shell history, or a commit. Example claude_desktop_config.json (replace the placeholder):

{
  "mcpServers": {
    "asana-local": {
      "command": "uv",
      "args": ["--directory", "/Users/coffeemug/Programming/asana-local-mcp", "run", "asana-local-mcp"],
      "env": {"ASANA_ACCESS_TOKEN": "<local-secret>"}
    }
  }
}

If the token is missing or blank, the server exits with code 2 and logs exactly:

ASANA_ACCESS_TOKEN is missing from MCP configuration.

Optional: cap inline image bytes with ASANA_INLINE_IMAGE_MAX_BYTES (default 2097152, maximum 5242880).

Tools

All six tools are declared read_only. Every response is a structured envelope:

{
  "items": [],
  "returned_count": 0,
  "truncated": false,
  "next_cursor": null,
  "scope": {},
  "message": null
}

returned_count always equals len(items). When truncated is true, next_cursor or message explains how to continue; pass next_cursor verbatim into the next call of the same tool.

list_projects

Lists projects whose name contains text.

Parameter

Type

Required

Default

Maximum

Description

text

string

No

—

—

Case-insensitive name substring filter

limit

integer

No

25

100

Maximum projects to return

cursor

string

No

—

—

Continuation cursor from a prior call

Input:

{
  "text": "roadmap",
  "limit": 25,
  "cursor": null
}

Output items:

{
  "items": [
    {"gid": "1234567890123", "name": "Roadmap 2026", "permalink_url": "https://app.asana.com/0/0/1234567890123", "archived": false}
  ],
  "returned_count": 1,
  "truncated": false,
  "next_cursor": null,
  "scope": {"searched_project_gids": []},
  "message": null
}

Projects are scoped to the token's accessible workspaces. list_projects first enumerates workspaces visible to the token (up to 25, across at most 5 Asana API pages), then queries each workspace's project pages with an explicit workspace parameter — the current Asana API can require one for GET /projects. Project GIDs are deduplicated across workspaces. Results may be truncated across workspace and project pages; continue with next_cursor to resume.

search_tasks

Searches tasks across up to 25 explicitly selected projects. This is the only way to find tasks: discovery never leaves the selected projects.

Parameter

Type

Required

Default

Maximum

Description

project_gids

string array

Yes

—

25

Projects to scan (1–25 GIDs)

text

string

No

—

—

Case-insensitive task-name substring

completed

boolean

No

—

—

true/false to filter by completion

assignee_gid

string

No

—

—

Exact assignee GID

modified_after

string

No

—

—

ISO-8601 timestamp (e.g. 2026-08-01T00:00:00Z)

limit

integer

No

50

200

Maximum tasks to return

Input:

{
  "project_gids": ["1234567890123"],
  "text": "launch",
  "completed": false,
  "assignee_gid": null,
  "modified_after": "2026-08-01T00:00:00Z",
  "limit": 50
}

Output items are deduplicated task summaries with their selected-project memberships; a task in multiple selected projects appears once. If the result set is truncated, retry with a narrower filter or fewer projects.

get_task

Returns one task's detail fields plus normalized attachment metadata.

Parameter

Type

Required

Description

task_gid

string

Yes

Decimal Asana task GID

Input:

{
  "task_gid": "1234567890123"
}

Output items carry name, permalink_url, assignee, due_on, completed, modified_at, html_notes, text_notes, projects, parent, and attachments (metadata only — see the attachment policy).

list_task_comments

Lists comment stories for one task, newest and oldest per Asana's story order, under strict bounds.

Parameter

Type

Required

Default

Maximum

Description

task_gid

string

Yes

—

—

Decimal Asana task GID

limit

integer

No

100

500

Maximum comments to return

cursor

string

No

—

—

Continuation cursor from a prior call

Input:

{
  "task_gid": "1234567890123",
  "limit": 100,
  "cursor": null
}

Output items are comments with comment_gid, task_gid, text, html_text, created_at, created_by, and attachments (metadata only). Attachment metadata for comments is bounded by a shared per-call budget of 100 fetches; when that budget runs out, the envelope message says so. If the API repeats an offset, continuation stops and the envelope message explains that results may be incomplete.

search_comments

Searches comments across selected projects, task-first.

Parameter

Type

Required

Default

Maximum

Description

project_gids

string array

Yes

—

25

Projects to scan (1–25 GIDs)

task_text

string

No

—

—

Case-insensitive task-name filter applied before any story request

comment_text

string

No

—

—

Case-insensitive comment-text filter

task_limit

integer

No

50

100

Maximum tasks to scan

comment_limit

integer

No

100

500

Maximum comments to return

Input:

{
  "project_gids": ["1234567890123"],
  "task_text": null,
  "comment_text": "blocker",
  "task_limit": 50,
  "comment_limit": 100
}

The scope object reports searched_project_gids, candidate_task_count, and separate task_truncated / comment_truncated flags. task_limit and comment_limit exhaustion are reported independently in message.

get_attachment

Returns one attachment's safe metadata, optionally with its image rendered inline.

Parameter

Type

Required

Default

Description

attachment_gid

string

Yes

—

Decimal Asana attachment GID

include_image

boolean

No

false

Render the image inline when allowed

Input:

{
  "attachment_gid": "1234567890123",
  "include_image": false
}

Output items carry gid, name, resource_subtype, host, size, and parent. With include_image: true, a successful render adds an MCP image content block next to the metadata envelope; any rejection is reported as truncated: true with a reason in message. include_image: false never adds an image block.

Attachment policy

  • Task and comment output carries metadata only. Access links (download_url, view_url, permanent_url) are omitted from task and comment attachments by default, so ephemeral URLs never leak into model context through browsing.

  • get_attachment returns fresh, ephemeral access links only when you explicitly call it. Downloads may expire after a short time; re-call get_attachment for a fresh link.

  • permanent_url is only reachable with a valid Asana session in the same browser, so treat it as reference metadata, not a shared link.

  • view_url may not be present for every attachment.

  • Attachment bytes are fetched without the bearer token, with an Accept: image/* header only.

Image policy

Inline images are opt-in and strictly bounded:

  • Rendering happens only when get_attachment is called with include_image: true.

  • Only Asana-hosted attachments (host: "asana") are candidates.

  • Only allowlisted image MIME types render inline: image/png, image/jpeg, image/gif, image/webp.

  • Default cap: 2 MiB (ASANA_INLINE_IMAGE_MAX_BYTES=2097152); hard ceiling: 5 MiB (5242880). Larger images return a truncated: true envelope with a reason message instead of bytes.

  • No inline video, PDF, document, or other binary; known subtypes are rejected before any download.

  • Nothing is ever written to disk: no local files, no cache, no index.

Security and privacy

  • attachments:read is required for the attachment tools; tokens without that scope get safe authentication errors.

  • GET-only data plane: the client and the packaged entry point contain no POST/PUT/PATCH/DELETE path; the contract tests enforce this by inspecting the client source AST and by recording every request the transport makes.

  • No OAuth, webhooks, cache, index, or cloud deployment. The server is a stdio process on your machine; it stores no state between calls beyond the stateless cursors you pass back.

  • No arbitrary HTML URL fetches. Attachment discovery reads only data-asana-gid attributes from Asana HTML; URLs in HTML are never dereferenced.

  • No token, log, or header leakage. Tool errors, server logs, and structured envelopes are sanitized: bearer tokens become Bearer [REDACTED] and URLs become [REDACTED_URL]. Logs record only the tool name and exception class.

  • .env is excluded from version control (see .gitignore), and .env.example ships an empty token declaration with no secret.

Error messages

Every failure is returned as an error envelope whose message is safe to show. The full set:

Condition

Message

Missing/blank token

ASANA_ACCESS_TOKEN is missing from MCP configuration.

Non-decimal GID

<field> must be a nonempty Asana GID.

Limit out of range

<field> must be between <min> and <max>.

Bad timestamp

modified_after must be an ISO-8601 timestamp.

Bad continuation cursor

cursor is invalid for this request.

Authentication failure

Asana authentication failed or access is denied.

Missing resource

Requested Asana resource is unavailable or inaccessible.

Rate limit

Asana rate limit reached. Retry after a short delay.

Invalid response

Asana returned an invalid response.

Transient failure

Asana service is temporarily unavailable. Retry shortly.

Attachment bytes

Asana attachment bytes are unavailable. Retry shortly.

Pagination repeat

Asana pagination repeated a cursor.

Truncated results

Message names the bound and how to continue (for example More matching projects may be available; continue with next_cursor., Task result limit reached; narrow filters or reduce selected projects., More comments may be available; continue with next_cursor.)

Unexpected error

Asana query failed unexpectedly.

Narrowing or continuing truncated results: pass the returned next_cursor verbatim into the same tool with the same arguments to fetch the next batch; or lower limit / add filters so the request completes inside its bounds. Cursors are stateless and tied to the exact endpoint, task, and filters that produced them.

Local smoke test (manual, optional)

Never put a real credential in an automated test or a tracked file. This smoke test uses your local client configuration only.

  1. Start an MCP inspector or client pointed at the server. When run from this checkout, launch it with the local command, not uvx: npx @modelcontextprotocol/inspector -- uv --directory /Users/coffeemug/Programming/asana-local-mcp run asana-local-mcp, with the token injected through the client's env block as shown under Authentication. (uvx asana-local-mcp only applies to a published package.)

  2. Call list_projects with {"limit": 1} and confirm it returns an accessible project from your workspace.

  3. Verify shell output, server logs, and git status / git grep show no token, no Authorization header, and no attachment URL anywhere.

Development

uv run ruff check src tests    # lint
uv run mypy src                # strict type check
uv build                       # build wheel + sdist into dist/
uv run pytest -q               # full suite (no network; mock transport only)

The suite includes tests/test_read_only_contract.py, which pins the read-only contract: no mutation methods in the client, every recorded request is GET, the README documents exactly the six tools the server exposes, the tracked files carry no real secrets or signed access URLs, error adapters strip bearer/header/URL fragments, and the whole suite passes with ASANA_ACCESS_TOKEN absent. No test makes a live Asana request.

Available Tools

6 tools
get_attachmentB
Read-only

Fetch one attachment, optionally rendering its image inline.

ParametersJSON Schema
NameRequiredDescriptionDefault
include_imageNo
attachment_gidYes

TDQS

B3.3/5.0
Behavior3/5

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

The readOnlyHint annotation already covers the safety profile, and the description is consistent with it. The phrase 'optionally rendering its image inline' adds a small behavioral detail tied to include_image, but the description does not clarify what the fetched attachment actually returns or what happens when inline rendering is false.

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

Conciseness5/5

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

One short sentence with no filler, and the core operation is front-loaded before the optional rendering behavior. Every word earns its place.

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

Completeness2/5

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

With no output schema, the description must explain what the returned attachment actually is—binary content, metadata object, URL, or rendered inline image—but it leaves this ambiguous. It also omits prerequisites and error behavior, making it incomplete for an agent to invoke confidently.

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

Parameters2/5

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

Schema description coverage is 0%, so the description needed to carry more weight. It gives some meaning to include_image via 'rendering its image inline,' but attachment_gid receives no elaboration beyond the obvious 'which attachment,' and no value formats or constraints are provided.

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

Purpose5/5

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

The description names a specific verb and resource ('Fetch one attachment') and adds a distinct behavioral caveat about optional inline image rendering. This clearly separates it from sibling tools that target projects, tasks, or comments.

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

Usage Guidelines2/5

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

There is no guidance about when to choose get_attachment over the sibling tools or what prerequisites apply, such as first obtaining the attachment_gid from a task. The only implied context is the resource name, which is not enough routing guidance.

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

get_taskA
Read-only

Fetch one task's detail fields and normalized attachments.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_gidYes

TDQS

A3.6/5.0
Behavior3/5

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

The readOnlyHint annotation already covers the safety profile, and the description is consistent with it ('Fetch' is read-only). The description adds modest context by mentioning that attachments are normalized, but it does not disclose potential behaviors like error cases, auth requirements, or how normalization works.

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

Conciseness5/5

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

The description is a single, front-loaded sentence with no filler. It states the action, the resource, and the specific output scope efficiently.

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

Completeness3/5

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

For a simple one-parameter read tool, the description covers the core purpose and output shape. However, it lacks parameter guidance, usage context, and any detail about how attachments are normalized or what 'detail fields' includes. The absence of an output schema makes this a more noticeable gap.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for the undocumented task_gid parameter. It only implies that the task is identified somehow, without explaining that task_gid is the unique identifier or providing any format/source context. The parameter name and title are self-explanatory, but the description adds little semantic value beyond that.

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

Purpose5/5

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

The description uses the specific verb 'Fetch' and names the resource and scope: one task's detail fields and normalized attachments. This clearly distinguishes it from siblings like search_tasks (search) and list_task_comments (comments only).

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

Usage Guidelines3/5

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

The description implies usage: use this when you need the detail fields and attachments of a single task, identified by task_gid. However, it does not explicitly state when to prefer this over siblings such as search_tasks or get_attachment, nor does it mention any exclusions.

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

list_projectsA
Read-only

List up to limit projects whose name contains text.

ParametersJSON Schema
NameRequiredDescriptionDefault
textNo
limitNoMaximum projects to return.
cursorNo

TDQS

A3.7/5.0
Behavior3/5

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

The description adds the substring-matching behavior for 'text' and clarifies the limit operation, but annotations already declare readOnlyHint=true. It does not disclose pagination behavior, default limits, ordering, or other operational details beyond the basic listing behavior.

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

Conciseness5/5

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

One sentence with no filler, front-loading the primary action and parameters. The backtick formatting helps distinguish parameters from prose.

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

Completeness3/5

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

For a 3-parameter tool with no output schema, the description covers the core listing behavior but fails to explain the 'cursor' parameter (pagination) or that 'text' can be null to list all projects. This leaves an agent uncertain about full tool usage.

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

Parameters3/5

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

Schema description coverage is only 33%, so the description must compensate. It explains that 'text' filters by project name and 'limit' sets the maximum projects, but it omits 'cursor' entirely and doesn't note that 'text' is optional or that limit defaults to 25.

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

Purpose5/5

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

The description states a specific verb ('List'), resource ('projects'), and a filter criterion ('name contains text'). This clearly distinguishes it from sibling tools that operate on tasks, attachments, and comments.

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

Usage Guidelines3/5

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

Usage is implied by the tool name and description: call it when you need a filtered list of projects. However, it offers no explicit guidance on when to use this over alternatives, nor does it mention any exclusions or prerequisites.

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

list_task_commentsB
Read-only

List up to limit comment stories for one task.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum comments to return.
cursorNo
task_gidYes

TDQS

B3.3/5.0
Behavior3/5

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

The annotations already declare readOnlyHint=true, so the description does not need to establish safety. It adds the 'one task' scoping and 'comment stories' terminology, but does not explain pagination behavior beyond the schema's cursor field. 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.

Conciseness5/5

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

A single sentence that front-loads the main functionality and limit constraint. There is no redundant filler or restating of the tool name.

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

Completeness3/5

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

For a read-only list operation with a simple schema, the description is minimally viable. However, it fails to explain cursor semantics and does not describe the returned comment story structure, which would be valuable given there is no output schema.

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

Parameters2/5

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

Schema description coverage is only 33%: only limit is described. The description clarifies the purpose of limit and task_gid, but cursor is left entirely unexplained, which is needed for paginated listing. This is only partial compensation for the schema gap.

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

Purpose4/5

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

The description specifies a clear verb ('List') and resource ('comment stories') scoped to a single task. It differsnciates from siblings like list_projects and search_coments because it is clearly per-task, though it does not explicitly name an alternative tool.

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

Usage Guidelines3/5

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

The phrase 'for one task' implies the tool is for fetching a task's comment stream, but there is no explicit guidance on when to prefer this over search_comments or other sibling tools. The intended context is inferable but not stated.

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

search_commentsC
Read-only

Search comments across selected projects.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_textNo
task_limitNoMaximum tasks to scan.
comment_textNo
project_gidsYes
comment_limitNoMaximum comments to return.

TDQS

C2.9/5.0
Behavior3/5

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

The annotations declare readOnlyHint=true, and the description is consistent with a read-only search operation. The description adds the project-scoping behavior, but provides no detail on filtering semantics, limits' effects, or what is returned.

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

Conciseness4/5

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

The description is a single front-loaded sentence with no wasted words. However, it is so brief that it omits useful behavioral details, making it concise but not fully 'appropriately sized' for an agent.

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

Completeness2/5

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

With five parameters, optional filters, no output schema, and sibling tools that overlap in purpose, the description is too sparse. It does not explain search semantics, defaults, return shape, or when to prefer list_task_comments or search_tasks.

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

Parameters2/5

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

Schema description coverage is only 40%, covering the two limit parameters. The required project_gids is understandable from its name, but task_text and comment_text have no description and the tool description does not explain how they are used, whether filters combine, or what matching logic applies.

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

Purpose4/5

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

The description identifies a specific verb ('search'), a resource ('comments'), and a scope ('across selected projects'). This distinguishes it from list_task_comments, which implies per-task listing, though it does not fully explain the search criteria or differentiate it from search_tasks.

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

Usage Guidelines2/5

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

There is no explicit guidance on when to use this tool versus its siblings. The phrase 'across selected projects' hints at multi-project search, but no exclusions or alternatives are mentioned, so an agent must infer usage from sibling names alone.

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

search_tasksA
Read-only

Search tasks across up to 25 selected projects.

ParametersJSON Schema
NameRequiredDescriptionDefault
textNo
limitNoMaximum tasks to return.
completedNo
assignee_gidNo
project_gidsYes
modified_afterNo

TDQS

A3.6/5.0
Behavior3/5

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

The readOnlyHint annotation already establishes that this is a safe read operation, and the description's word 'Search' aligns with that. The description adds the cross-project scope but does not disclose behavior like result ordering, pagination, or how filters interact. Given the annotation coverage, this is adequate 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.

Conciseness5/5

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

The description is a single concise sentence that front-loads the tool's core purpose and key constraint. There is no filler or redundant restating of the schema.

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

Completeness3/5

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

For a tool with six parameters and no output schema, the description is somewhat thin. It omits useful invocation details such as how search text and filters combine, what task fields are matched, and what the response contains. Still, the schema provides parameter names and the annotation confirms read-only safety, so the tool is callable with moderate confidence.

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

Parameters2/5

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

Schema description coverage is only 17%, and the description itself adds almost no parameter-level meaning beyond 'selected projects' pointing at project_gids. It does not explain text search semantics, the completed filter, assignee filtering, or modified_after behavior, all of which would help an agent use the tool correctly.

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

Purpose5/5

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

The description clearly states a specific action ('Search'), a specific resource ('tasks'), and the key scope boundary ('across up to 25 selected projects'). This distinguishes it from siblings like get_task and search_comments without ambiguity.

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

Usage Guidelines3/5

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

The description gives enough context to infer when to use this tool: when you need to find tasks across one or more selected projects. However, it does not explicitly name alternatives or state when not to use it, so the routing decision is left mostly to the agent.

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

Tool Schema Changelog

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

  1. 6 tool updatesv0.1.0
    • First observedget_attachment
    • First observedget_task
    • First observedlist_projects
    • First observedlist_task_comments
    • First observedsearch_comments
    • First observedsearch_tasks
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a clearly distinct resource and action: projects, tasks, task comments, project-scoped comments, and attachments. The two comment tools are separated by scope (single task vs. selected projects), so an agent should be able to select the correct one.

Naming Consistency5/5

All tool names use lowercase snake_case with an action-plus-noun pattern like list_projects, search_tasks, get_task, and get_attachment. The naming is consistent and predictable.

Tool Count5/5

Six tools is a well-scoped size for a focused read/search integration. Each tool has a distinct purpose and none feel redundant or extraneous.

Completeness4/5

For the apparent read-only/local-search purpose, the major Asana resources are covered: projects, tasks, comments, and attachments, with reasonable retrieval chains. The main limitation is the lack of any create/update/delete tools, which would be a gap if full Asana lifecycle management were expected.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers