Skip to main content
Glama

List projects

list_projects
Read-only

List security analysis projects for the authenticated user, one page at a time.

Browse projects or find one covering a repository. Each project's
repositories array includes owner and repository. Use that match to get
project_id or project_name for other tools.

A reply with next_cursor is one page of a longer list. Call again with it
as cursor until a reply has none.

Each project's ticketing says whether Trent files tickets for its tasks in
the team's issue tracker, and where. To make a project, use create_project;
to change one, update_project. A project_name two projects share is
refused by the other tools; pass project_id instead.

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": "list_projects"
  }
}

Input Schema

NameRequiredDescriptionDefault
cursorNoOpaque cursor from a previous call's `next_cursor`.

Output Schema

NameRequiredDescriptionDefault
errorNoTrue when the call itself failed. False for successful calls, including a scan still running, an already approved plan, or a repository classified as non-agentic. The reason field describes these workflow states.
reasonNoA stable snake_case code from the allowed set. Present on every error and on successful calls that carry a workflow state.
messageNoExactly one sentence written for the user. Never raw exception text or a backend error string, which may expose private details.
metadataNoCaller metadata, such as 'expiration_warning'. Substantive results have their own fields. Never includes exception or backend error text, which may expose private details.
projectsNoProjects available to the authenticated user.
next_stepsNoRecommended next actions, in order.
next_cursorNoPass back as `cursor` to read the next page of projects. Absent when this is the last page, so a list with no next_cursor is the whole list.
retry_after_secondsNoWith reason rate_limited, how many seconds Trent asks the caller to wait.
ticket_destination_unavailableNoTrue after a failed read of the ticket destination. Project ticket destinations are then absent, while each project's ticketing switch remains visible.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / $defs / DocumentRead / properties / type / description
      Previous value: -"What the document is: source_code, design_doc, user_rule, code_diff, openclaw_config, openclaw_deployment or external_findings."New value: +"What the document is: source_code, design_doc, user_rule, code_diff, openclaw_deployment or external_findings."
  2. Changed3 schema fields changed
    • addedInput schema / properties / cursor
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Opaque cursor from a previous call's `next_cursor`.",
      +  "title": "Cursor"
      +}
    • addedOutput schema / properties / next_cursor
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Pass back as `cursor` to read the next page of projects. Absent when this is the last page, so a list with no next_cursor is the whole list.",
      +  "title": "Next Cursor"
      +}
    • addedOutput schema / properties / retry_after_seconds
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "With reason rate_limited, how many seconds Trent asks the caller to wait.",
      +  "title": "Retry After Seconds"
      +}
  3. Changed5 schema fields changed
    • changedOutput schema / $defs / ListedProject / properties / latest_commit_sha / description
      Previous value: -"The commit of the first repository that the current full report analysed."New value: +"The commit of the first repository that the current full report analysed: the last completed scan's commit, not a running scan's."
    • addedOutput schema / $defs / ListedProject / properties / running_scan_repositories
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "$ref": "#/$defs/ScanRepoCommitView"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "While a scan runs, the repositories it reads and the commit in each. Absent when no scan runs and until the running scan has recorded its cloned commits.",
      +  "title": "Running Scan Repositories"
      +}
    • changedOutput schema / $defs / ScanProgressView / properties / job_phase / description
      Previous value: -"Sub-step within the current stage as an ordinal, such as '3/6'. The count covers this stage. Absent until the stage reports a sub-step and at an approval gate."New value: +"Sub-step within the current stage as an ordinal, such as '3/6'. The count is the running stage plan's own, which is shorter for an incremental scan. Absent until the stage reports a sub-step, at an approval gate, and when the stage is not running."
    • changedOutput schema / $defs / ScanProgressView / properties / scan_phase / description
      Previous value: -"Running stage as an ordinal, such as '1/3'. The denominator is the pinned graph's stage count and stays fixed throughout the scan. Use it to describe progress. Do not branch on it or convert it to a percentage: stages have different lengths, with seven sub-steps in secure and two in plan. Absent at an approval gate or after a failure to load the pinned graph."New value: +"Running stage as an ordinal, such as '1/3'. The denominator is the pinned graph's stage count and stays fixed throughout the scan. Use it to describe progress. Do not branch on it or convert it to a percentage: stages have different lengths, and a stage's sub-step count differs between full and incremental scans. Absent at an approval gate or after a failure to load the pinned graph."
    • addedOutput schema / $defs / ScanRepoCommitView
      Added value: +{
      +  "description": "One repository a scan read, and the commit it read there.\n\nA source commit SHA is a public identifier of the caller's own repository,\nnot a Trent internal; the project read and the report markdown already\npublish the same value. The basis's derived id stays server-side: it is a\nhash over the whole source set, which is the class of value this projection\ndrops.",
      +  "properties": {
      +    "commit_sha": {
      +      "description": "The full commit SHA the scan cloned.",
      +      "title": "Commit Sha",
      +      "type": "string"
      +    },
      +    "owner": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "description": "The repository owner, when the source names one.",
      +      "title": "Owner"
      +    },
      +    "repo_slug": {
      +      "description": "The repository's slug on the project, such as owner/name.",
      +      "title": "Repo Slug",
      +      "type": "string"
      +    },
      +    "repository": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "default": null,
      +      "description": "The repository name, when the source names one.",
      +      "title": "Repository"
      +    }
      +  },
      +  "required": [
      +    "commit_sha",
      +    "repo_slug"
      +  ],
      +  "title": "ScanRepoCommitView",
      +  "type": "object"
      +}
  4. Changed1 schema field changed
    • addedOutput schema / $defs / ListedProject / properties / latest_complete_scan_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The scan that produced the project's current full report, the scan_id GET /analyse names when it serves that report. Absent before the first complete scan and on projects older than scans.",
      +  "title": "Latest Complete Scan Id"
      +}
  5. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real operational detail beyond that, namely the cursor/next_cursor loop contract and the meaning of each project's ticketing field. It stops short of describing ordering or page size, which would have made it fully transparent.

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 purpose and pagination rule are front-loaded, and each paragraph carries distinct information (scope, cursor loop, ticketing, sibling routing). A few lines, such as the repositories-match sentence, restate what the output schema likely shows and could be trimmed.

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 paginated list tool with an output schema and full annotation coverage, the description covers the pagination contract, the naming-conflict pitfall, and routing to create/update. Nothing an agent needs to invoke it correctly is missing.

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 the single cursor parameter is already documented in the schema as an opaque value from next_cursor. The description reinforces how the cursor is obtained and when to stop, but adds no format or edge-case detail beyond the schema's own wording.

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 opening sentence gives a specific verb and resource (list security analysis projects) plus the scope (authenticated user, paginated). It explicitly separates itself from create_project and update_project, so an agent can pick it out of the sibling list without opening any schema.

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

Usage Guidelines5/5

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

It states both use cases (browse, or find the project covering a repository) and names the tools to use for the other operations (create_project, update_project). It also gives an operational exclusion: a shared project_name is refused by other tools, so pass project_id instead.

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.