Skip to main content
Glama

project_list

Read-onlyIdempotent

My projects, my apps, my sites, my deployments, account inventory, dashboard overview — show every project I own or collaborate on. Each row includes is_owner so you can tell which is which.

Compact + paginated by default to keep the payload small: returns up to 50 projects with the core fields (id, name, subdomain, status, tags, created_at, last_deployed_at, latest_screenshot_url, favicon_url, is_owner). The render fields are included in this one response; screenshot/favicon URLs are null until their live-release asset exists. When more exist, the response ends with a note telling you the total and how to page. To narrow or expand: pass q (substring filter on name/subdomain), tag (organization label filter; multiple values combine with AND), limit/offset (paging), or fields:"full" for the complete record per row.

Example:

// project_list({ q: "saas", limit: 50 }) returns:
[
  { "id": "p_abc123", "name": "My SaaS", "subdomain": "my-saas", "status": "deployed", "last_deployed_at": "2026-04-01T...", "latest_screenshot_url": "https://api.somewhere.cloud/v1/deploy-screenshots/p_abc123/v7-desktop.png?exp=...&sig=...", "favicon_url": "https://my-saas.somewhere.site/favicon.ico", "tags": ["marketing"], "is_owner": true },
  { "id": "p_xyz789", "name": "Jen's App", "subdomain": "jen-app", "status": "draft", "last_deployed_at": null, "latest_screenshot_url": null, "favicon_url": null, "tags": [], "is_owner": false }
]

Shared projects: you can deploy, edit files, run db migrations, send email, and use AI — all billed to the project owner. You cannot delete, transfer, change env var values, or manage billing/spend caps on shared projects.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "project_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoOptional substring filter matched against project name and subdomain for locating a specific project without paging the whole list.
tagNoOptional organization-tag filter. Tags normalize to lowercase letters, digits, and hyphens. One tag or an array is accepted; arrays use AND semantics.
limitNoMaximum rows to return (default 50). The compact list is paginated; larger limits or `offset` cover accounts with many projects.
fieldsNoResponse shape. "compact" (default) returns identity, status, tags, render-ready asset URLs, deploy time, and ownership. "full" adds the heavier complete project record.
offsetNoRow offset for paging (default 0). Together with `limit`, it traverses a long list; the response note reports the total count.

Output Schema

NameRequiredDescriptionDefault
okNo
dataNo
errorNo
messageNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already cover read-only and idempotent, and the description adds real value on top: pagination defaults (50 rows), a trailing note with the total, and the caveat that screenshot/favicon URLs are null until a live release exists. The shared-project permission paragraph discloses what a non-owner can and cannot do, which is useful for interpreting `is_owner: false`, though it is more product policy than list behavior.

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

Conciseness3/5

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

The core behavior is front-loaded well with bolded headings, but the block is long: a multi-line JSON example for a listing tool whose output schema already exists, plus a trailing shared-projects permissions paragraph that does not affect how the tool is called. Roughly a third of the text could be cut without loss.

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

Completeness5/5

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

For a five-parameter list tool with full schema coverage, annotations, and an output schema, everything an agent needs is present: paging behavior, default payload shape, null-URL caveat, and how the total count is surfaced. No gaps remain that would cause a mis-call.

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

Parameters3/5

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

Schema coverage is 100% and every parameter is already documented there, including tag AND semantics and the compact/full enum. The description largely restates that (substring filter, 50 default, `fields:"full"`), with the worked JSON example being the only genuine addition. Baseline 3 is appropriate.

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?

Opens with a specific verb and resource ('show every project I own or collaborate on') and names account inventory / dashboard overview as the same thing, so scope is unambiguous. It also explains the `is_owner` column, which lets an agent separate owned from shared projects without another call.

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

Usage Guidelines4/5

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

Clear guidance on how to narrow or expand the list (`q`, `tag`, `limit`/`offset`, `fields:"full"`) and what the default payload looks like. It never routes the agent to alternatives though — nothing tells it to use `project_get` for a single project or a search tool for cross-account lookup.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources