Skip to main content
Glama
SalehKhatri

postman-mcp

by SalehKhatri

Postman MCP

A Model Context Protocol (MCP) server that provides seamless integration with the Postman API. This package enables AI assistants and applications to interact with Postman workspaces, collections, requests, environments, and folders programmatically.

NPM Version License: MIT

🚀 Features

📁 Workspace Management

  • List all workspaces

  • Get detailed workspace information

  • Create new workspaces (personal/team)

  • Update workspace metadata

📚 Collection Management

  • List collections within workspaces

  • Get collection details with full structure

  • Create new collections

  • Update collection metadata and variables

  • Delete collections

🔧 Request Management

  • Add new HTTP requests to collections

  • Update existing requests (method, URL, headers, body)

  • Move requests between folders

  • Delete requests

  • Support for all HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)

🌍 Environment Management

  • List environments in workspaces

  • Get environment details and variables

  • Create new environments with variables

  • Update environment variables

  • Delete environments

  • Support for secret, default, and custom variable types

📂 Folder Organization

  • Create nested folder structures

  • Organize requests within folders

  • Support for hierarchical folder paths

Related MCP server: MCP Server

⚙️ Setup

1. Get Your Postman API Key

  1. Go to Postman Account Settings

  2. Click "Generate API Key"

  3. Give it a name and copy the generated key

2. MCP Configuration

For Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "postman": {
      "command": "npx",
      "args": ["postman-mcp"],
      "env": {
        "POSTMAN_API_KEY": "your_postman_api_key_here"
      }
    }
  }
}

For Cursor

Add the configuration to your Cursor settings:

{
  "mcp": {
    "servers": {
      "postman": {
        "command": "npx postman-mcp",
        "env": {
          "POSTMAN_API_KEY": "your_postman_api_key_here"
        }
      }
    }
  }
}

For Warp

Add the following to your Warp session setup:

{
  "postman": {
    "command": "npx",
    "args": ["postman-mcp"],
    "env": {
      "POSTMAN_API_KEY": "your_postman_api_key_here"
    },
    "working_directory": null,
    "start_on_launch": true
  }
}

For Other MCP Clients

Use the standard MCP server connection with:

  • Command: npx postman-mcp or node path/to/postman-mcp/dist/index.js

  • Transport: stdio

  • Environment: Set POSTMAN_API_KEY

🛠️ Development Setup

Prerequisites

  • Node.js 18+

  • npm or yarn

  • Postman API key

Local Development

  1. Clone the repository:

    git clone https://github.com/SalehKhatri/postman-mcp.git
    cd postman-mcp
  2. Install dependencies:

    npm install
  3. Set up environment:

    cp .env.example .env
    # Edit .env and add your POSTMAN_API_KEY
  4. Build the project:

    npm run build
  5. Run in development mode:

    npm run dev

🔍 Available Tools

Workspace Operations

  • list_workspaces - Get all workspaces

  • get_workspace - Get workspace details

  • create_workspace - Create new workspace

  • update_workspace - Update workspace info

Collection Operations

  • list_collections - Get collections in workspace

  • get_collection - Get full collection structure

  • create_collection - Create new collection

  • update_collection - Update collection metadata

  • delete_collection - Remove collection

Request Operations

  • add_request - Add HTTP request to collection

  • update_request - Modify existing request

  • delete_request - Remove request from collection

Environment Operations

  • list_environments - Get environments in workspace

  • get_environment - Get environment variables

  • create_environment - Create new environment

  • update_environment - Modify environment variables

  • delete_environment - Remove environment

Folder Operations

  • create_folder - Create folder in collection

💡 Usage Examples

Basic Workflow

// List all workspaces
const workspaces = await mcp.callTool("list_workspaces", {});

// Get collections in a workspace
const collections = await mcp.callTool("list_collections", {
  workspaceId: "workspace-id",
});

// Create a new request
await mcp.callTool("add_request", {
  collectionUid: "collection-uid",
  name: "Get Users",
  method: "GET",
  url: "https://api.example.com/users",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer {{token}}",
  },
  folder: "API/Users",
});

// Create an environment
await mcp.callTool("create_environment", {
  name: "Production",
  workspaceId: "workspace-id",
  values: [
    {
      key: "base_url",
      value: "https://api.production.com",
      type: "default",
    },
    {
      key: "api_key",
      value: "secret-key",
      type: "secret",
    },
  ],
});

🔐 Security

  • API Key Protection: Store your Postman API key securely using environment variables

  • Scope Limitation: The API key should have minimal required permissions

  • Network Security: All requests use HTTPS to communicate with Postman API

🤝 Contributing

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

  • Create an issue for bug reports or feature requests

  • Check existing issues before creating new ones

  • Provide detailed information including error messages and environment details


Made with ❤️ for the developer community

Available Tools

19 tools
add_requestC

Add a new request to a collection

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesRequest URL
bodyNoRequest body (will be stringified if object)
nameYesName of the request
folderNoFolder path (e.g., "folder1/folder2")
methodYesHTTP method
headersNoRequest headers as key-value pairs
descriptionNoRequest description
collectionUidYesThe UID of the collection

TDQS

C2.8/5.0
Behavior1/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It merely restates the operation name without mentioning side effects, required field validations, return values, or potential errors. This is essentially a tautology with no additional behavioral information.

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, concise sentence that avoids wasted words. It is front-loaded and direct, though it sacrifices substance for brevity.

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

Completeness1/5

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

This 8-parameter tool with no annotations or output schema requires substantial context. The description provides none: no mention of required fields, return values, prerequisites, or behavior. It is severely incomplete for a tool of this complexity.

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?

The schema provides 100% coverage for all 8 parameters, each with descriptions, so the baseline is 3. The tool description adds no parameter-level information, but the schema fully documents the parameters, making this adequate.

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 the action ('Add'), the resource ('request'), and the target ('a collection'). It distinguishes from sibling tools like update_request and delete_request, 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.

Usage Guidelines2/5

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 update_request for modifications or create_collection for collections. The description only states the action without any context on prerequisites or exclusions.

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

create_collectionB

Create a new collection

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the collection
descriptionYesThe description of the collection
workspaceIdYesThe ID of the workspace

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral transparency. It merely states the creation action without disclosing side effects, permission requirements, whether the operation is reversible, or what the response contains. For a mutation tool, this is a significant gap.

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 with no unnecessary words. It front-loads the verb and resource, making it immediately clear what the tool does. All tokens earn their 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?

For a simple create operation with no output schema and no annotations, the description is insufficiently complete. It does not explain what happens after creation, whether any preconditions exist (e.g., workspace existence), or what the return value looks like. The schema covers parameters, but the description does not provide the broader context an agent needs to invoke the tool confidently.

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?

The input schema provides 100% coverage with descriptions for all three parameters (name, description, workspaceId). The description itself adds no additional parameter semantics, but the schema already documents the parameters adequately, so the baseline score of 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?

The description 'Create a new collection' uses a specific verb ('create') and resource ('collection'), clearly distinguishing it from sibling tools like update_collection, delete_collection, and list_collections. There is no ambiguity about what action is performed.

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?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., that the workspaceId must reference an existing workspace) or exclusions (e.g., that this tool does not modify existing collections). This is a minimal restatement of the tool's name.

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

create_environmentC

Create a new environment

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesName of the environment
valuesNoValues for the environment
workspaceIdYesThe ID of the workspace

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It simply states the action without mentioning permissions, side effects, duplicate handling, or what response to expect. For a mutating operation, this is a significant gap.

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 description is concise and front-loaded, with no wasted words. However, it is overly terse and provides minimal information, arguably crossing from conciseness into under-specification. It gets a middle score for being efficient but not sufficiently informative.

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?

Given the absence of an output schema and annotations, the description should at least indicate what the tool returns (e.g., the created environment object) or clarify constraints like required permissions. It does neither, leaving the tool's behavior incomplete for the agent to use correctly.

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?

The input schema provides detailed descriptions for all three parameters, including name, workspaceId, and the values array structure. Since schema coverage is 100%, the description does not need to repeat parameter info. However, it also adds no extra semantic value beyond the schema, 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.

Purpose4/5

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

The description 'Create a new environment' uses a specific verb (create) and resource (environment), clearly distinguishing it from sibling tools like update_environment and delete_environment. However, it does not elaborate on what an environment consists of (e.g., variables), so it stops short of a fully helpful definition.

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?

No usage guidance is provided. The description does not mention when to use this tool versus create_collection or create_workspace, nor does it state any prerequisites or context for creating an environment. The agent is left to infer usage from the tool name alone.

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

create_folderC

Create a new folder in a collection

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNameYesName of the folder to create
parentFolderNoParent folder path (optional)
collectionUidYesThe UID of the collection

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries full responsibility for disclosing behavioral traits. It only states the action 'Create' without detailing side effects, permissions required, whether the collection must exist, or what the response format is. This is insufficient for a mutation tool.

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, concise sentence with no redundant phrasing. It is front-loaded with the action and resource, but it lacks any additional structuring like alternative guidance or context, which prevents a perfect score.

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?

For a tool with three parameters and no output schema or annotations, the description is incomplete. It does not explain return values, error conditions, or any prerequisites. The limited scope of the tool somewhat mitigates this, but the description still leaves significant gaps.

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?

The input schema already provides complete descriptions for all three parameters, including folderName, parentFolder, and collectionUid. The description adds no additional semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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 uses a specific verb and resource ('Create a new folder') and specifies the context ('in a collection'), making the tool's purpose clear. However, it does not explicitly distinguish from sibling tools like create_collection or add_request, though the resource type 'folder' differentiates it implicitly.

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?

The description provides no guidance on when to use this tool versus alternatives such as create_collection or add_request. It does not mention prerequisites like collection existence or when not to use it, so usage context is entirely absent.

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

create_workspaceC

Create a new workspace

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the workspace
typeYesThe type of the workspace
descriptionYesThe description of the workspace

TDQS

C2.9/5.0
Behavior1/5

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It only says 'Create a new workspace,' which restates the action without revealing any side effects, permissions, reversibility, or response details. This is a significant gap for a mutation tool.

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 sentence with no filler or redundant information. It is efficiently packed and front-loaded with the core action and resource, earning full marks for conciseness.

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?

The tool is a simple create operation with a complete input schema, but it has no output schema and no annotations. The description fails to disclose what the response will be or any outcome of the operation. For a creation tool, this leaves a meaningful gap in understanding what happens after the 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 description coverage is 100% (all three parameters have descriptions), so the baseline is 3. The description does not add any additional meaning or context for parameters beyond what the schema already provides, which is acceptable but not additive.

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 clearly states the action ('Create') and the resource ('a new workspace'), which is a distinct resource from sibling tools like create_collection. However, it does not explicitly differentiate itself from these siblings, so it scores a 4 rather than a 5.

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 tool when you need to create a workspace. It does not provide explicit context about when to choose this over alternatives, nor does it mention any prerequisites or exclusions, so it falls at the 'implied usage' level.

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

delete_collectionB

Delete a Postman collection

ParametersJSON Schema
NameRequiredDescriptionDefault
collectionUidYesThe UID of the collection to delete

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the action 'Delete' but does not disclose that the operation is destructive, permanent, or may require specific permissions. No details about side effects or error conditions are given.

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 immediately conveys the tool's purpose. It contains no fluff or redundant information, earning a top score for efficiency.

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 delete operation with one fully documented parameter, the description is minimally adequate. However, given that it is a destructive mutation with no annotations and no output schema, it lacks context about permanence, return values, or failure modes, making it not fully complete.

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 100%, and the parameter 'collectionUid' is well-described as 'The UID of the collection to delete'. The description adds no additional meaning beyond the schema, but the schema itself is sufficient, so the baseline of 3 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 'Delete a Postman collection' clearly specifies the verb (delete) and resource (Postman collection). It is unambiguous but does not explicitly distinguish from siblings like delete_request or delete_environment, though the resource type is clear.

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?

No guidance is provided on when to use this tool versus alternatives such as update_collection or list_collections. There is no mention of prerequisites, conditions, or exclusions, leaving the agent to infer usage solely from the tool name.

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

delete_environmentC

Delete an existing environment

ParametersJSON Schema
NameRequiredDescriptionDefault
environmentUidYesThe UID of the environment to delete

TDQS

C2.9/5.0
Behavior2/5

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

No annotations exist, and the description only says 'delete' without disclosing irreversibility, permission requirements, or cascade effects. It fails to add behavioral context beyond the action itself.

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?

It is a single sentence with no redundancy, but it is also nearly a tautology given the tool name. It is efficient, though it could include more substance; still, it earns a 4.

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?

For a destructive mutation tool with no annotations and no output schema, the description is minimal. It lacks information about consequences, error conditions, or return values, making it incomplete for safe 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?

The input schema fully describes the single parameter (environmentUid), and the description adds no additional meaning. The high schema coverage warrants the baseline score of 3.

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 clearly states a delete action targeting an environment resource, distinguishing it from sibling tools like create/update/list. However, it does not elaborate on scope or effect, so it is not a 5.

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?

No guidance is provided on when to use this tool versus alternatives, no prerequisites or exclusions are mentioned. The description simply states the action without any contextual guidance.

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

delete_folderC

Delete a folder from a collection

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNameYesName of the folder to delete
parentFolderNoParent folder path (optional)
collectionUidYesThe UID of the collection

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Delete' implies destructiveness, but no details are given about permanence, cascading effects (e.g., deleting subfolders), or required conditions. This is a significant gap for a mutation tool.

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 sentence that is front-loaded with the action and resource. It contains no filler or redundant information, making it highly concise and well-structured.

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?

Despite being a simple tool, the description lacks critical context such as deletion scope (recursive or not), preconditions (e.g., folder must exist), and potential error behavior. The schema covers parameters, but the behavior is under-specified.

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?

The input schema provides 100% coverage of all parameters with descriptions. The description itself does not add any parameter semantics beyond what the schema already states, so the baseline score of 3 is appropriate.

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 clearly states the action (Delete) and the resource (a folder from a collection). It differentiates from sibling tools like delete_collection by specifying 'folder', though it does not explicitly contrast with alternatives.

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 on when to use this tool versus alternatives, prerequisites, or conditions under which deletion is appropriate. The description only states the action itself, leaving the choice of tool implicit.

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

delete_requestB

Delete a request from a collection

ParametersJSON Schema
NameRequiredDescriptionDefault
requestNameYesName of the request to delete
collectionUidYesThe UID of the collection

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It simply states 'Delete a request' but does not disclose that the operation is permanent, irreversible, or requires specific permissions. For a destructive action, this lack of context is a significant gap.

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, focused sentence with no wasted words. It is front-loaded and immediately conveys the core purpose. Perfectly concise for the tool's simplicity.

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?

The tool is simple with complete schema coverage and no output schema. The description adequately states the action but omits any side-effect or precondition information, such as whether the request must exist or if the deletion is permanent. For a destructive operation, this feels minimally complete but not fully contextual.

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?

The input schema already provides 100% description coverage for both parameters (requestName and collectionUid). The description adds no additional parameter semantics. Baseline of 3 applies since the schema does the heavy lifting.

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 the action (delete) and the resource (request from a collection). It distinguishes itself from sibling tools like delete_collection and delete_folder by specifying the exact resource type. The verb is 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.

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is specifically for deleting a single request (vs. a collection or folder), nor does it reference any related tools. There is no conditional or exclusions context.

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

get_collectionB

Get detailed information about a specific collection

ParametersJSON Schema
NameRequiredDescriptionDefault
collectionUidYesThe UID of the collection.

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the burden. It only says 'Get detailed information' which is essentially a restatement of the tool name. It does not disclose error handling, permissions, or what constitutes 'detailed information'.

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 with no filler or redundant information. It earns its place by stating the core purpose 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 get tool with one fully-described parameter, the description is minimally adequate. However, with no output schema, it leaves ambiguity about what 'detailed information' includes and gives no indication of when to prefer this over list_collections.

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?

The input schema provides 100% coverage for collectionUid with a clear description. The tool description adds no additional parameter meaning, but none is needed given the schema's thoroughness.

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 identifies the tool's action ('Get') and resource ('collection'), and the phrase 'specific collection' differentiates it from list_collections. It unambiguously states the purpose.

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?

The description gives no guidance on when to use this tool versus alternatives (e.g., list_collections for multiple collections). The only usage signal is implicit in the name and sibling tool context.

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

get_environmentA

Get detailed information about a specific environment

ParametersJSON Schema
NameRequiredDescriptionDefault
environmentUidYesThe UID of the environment

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. The verb 'Get' implies a read-only operation, but the description does not disclose any additional behavioral aspects such as required permissions, error handling, or what exactly constitutes 'detailed information'. It is minimally transparent, neither misleading nor 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, clear sentence with no unnecessary words. It is front-loaded with the action and resource, achieving high conciseness and structure.

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?

While the tool is relatively simple, the description omits details about what 'detailed information' includes, especially since there is no output schema to clarify return values. It is sufficient for basic orientation but lacks completeness for an agent to anticipate the tool's full output.

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?

The input schema fully describes the only parameter, environmentUid, with its type and meaning. The description adds no extra semantic value beyond the schema, so the baseline of 3 applies.

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 the action ('Get') and the target resource ('detailed information about a specific environment'). The use of 'specific' distinguishes it from sibling tools like list_environments, which lists all environments, 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.

Usage Guidelines3/5

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

The description implies use when you have a specific environment UID, contrasting with list_environments for listing. However, it does not explicitly state when to use this over alternatives or provide any exclusions. The guidance is implicit rather than direct.

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

get_workspaceA

Get detailed information about a specific workspace

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceIdYesThe ID of the workspace

TDQS

A3.5/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It mentions 'detailed information' but does not specify what fields are returned, error behavior, or permissions needed. For a read operation, this is somewhat transparent, but the vagueness of 'detailed' leaves significant gaps.

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 sentence that is concise and front-loaded with the action and resource. No unnecessary words or repetition for a simple tool.

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?

Given the tool's simplicity (1 param, no output schema), the description is minimally adequate but could be more complete. It does not clarify what 'detailed information' includes, and with no output schema, the agent must guess the return structure. It is not egregiously incomplete, but could benefit from more explicit detail.

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?

The schema already provides 100% coverage for the single parameter (workspaceId). The description adds 'specific workspace' which aligns with the parameter, but does not add any additional meaning beyond the schema, such as format, examples, or usage notes.

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 the action ('Get') and the resource ('workspace'), and specifies 'specific' to distinguish it from listing all workspaces. This aligns with sibling tool list_workspaces and avoids 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 implies usage when you need details of one workspace, likely by ID, but does not explicitly state when to use this versus list_workspaces or provide any exclusions or alternative guidance. The word 'specific' gives a hint but lacks direct comparison.

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

list_collectionsB

List all collections in a workspace

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceIdYesThe ID of the workspace

TDQS

B3.4/5.0
Behavior2/5

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

No annotations are provided, so the description carries the burden of disclosing behavior. The description only states that it lists collections; it does not mention permissions, return format, pagination, or potential side effects. Since 'list' implies a read operation, but no details are given, the transparency 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.

Conciseness5/5

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

The description is a single concise sentence that communicates the tool's purpose without redundant wording. It is appropriately short and front-loaded.

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?

The description is very brief and does not explain the return value structure or any limitations. With no output schema or annotations, the agent lacks information about what the response contains or how the tool behaves in edge cases. For a simple list tool, more context would be expected.

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?

The schema already provides full description of the workspaceId parameter (coverage 100%). The description adds no additional meaning beyond mentioning 'in a workspace', which is redundant. Baseline scoring applies.

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 'List' and identifies the resource 'collections' and scope 'in a workspace', clearly distinguishing it from sibling tools like get_collection or create_collection. It accurately describes the function.

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 does not explicitly state when to use this tool or mention alternatives. The usage is implied by the verb 'List' and the resource, but no exclusion criteria or comparison to sibling tools like get_collection is provided.

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

list_environmentsC

List all environments

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceIdYesThe ID of the workspace

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description carries the full burden. It simply says 'List all environments' without disclosing that a workspaceId is required, whether it is a read-only operation, or any details about the response format. This is insufficient for a tool with no other behavioral info.

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 description is extremely short at five words, which is efficient but under-specified. It lacks essential context about workspace scoping and the nature of the result, making it more under-specification than good conciseness.

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?

Given that there is no output schema and no annotations, the description should explain the scope and return behavior. It does not specify that the list is filtered by workspaceId, nor what fields are returned. The presence of sibling tools like get_environment suggests a need to clarify the list vs. single-item distinction.

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?

The schema provides a full description for the only parameter (workspaceId), covering 100% of parameters. The tool description adds no additional meaning, such as how workspaceId filters the list. Baseline of 3 is appropriate since schema covers the parameter but the description doesn't enhance it.

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 uses a specific verb 'list' and resource 'environments', clearly identifying the action. However, it does not mention that environments are scoped to a workspace (evidenced by the required workspaceId), which distinguishes it from a global listing. Sibling tools like get_environment and list_workspaces are not referenced, but the basic purpose is clear.

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?

No usage guidance is provided. The description does not specify when to use this tool versus get_environment (for a single environment) or list_workspaces (for workspaces). There are no context cues for when this is the right choice.

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

list_workspacesB

List all workspaces

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3/5.0
Behavior1/5

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

There are no annotations, so the description carries the full burden of behavioral disclosure. It only states 'List all workspaces' without detailing pagination, return format, whether archived workspaces are included, or any access requirements. This lack of detail does not inform the agent about what to expect beyond the minimal action.

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 redundant words. It conveys the essential purpose without any filler. This is appropriately concise for a tool with no parameters.

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?

The tool is simple, but the description omits what a 'list all' operation returns (e.g., a list of workspace objects vs. names, pagination behavior). Given there is no output schema or annotations, the description is not enough for an agent to understand the full context of the invocation and response. More information on the return structure would provide completeness.

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

Parameters4/5

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

The input schema has zero parameters, and schema description coverage is 100% (vacuously, as there are no properties). Since there are no parameters, the baseline is 4, and the description adds nothing that detracts from this. It correctly implies no filtering or options.

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 'List all workspaces' clearly states the action (list) and the resource (workspaces). It uses a specific verb and resource, distinguishing it from sibling tools like 'get_workspace' which implies retrieving a single workspace.

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

Usage Guidelines1/5

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

No usage guidance is provided. The description does not mention when to use this tool versus alternatives such as 'get_workspace' for a single workspace or 'list_collections' for a different resource type. No exclusions or prerequisites are stated.

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

update_collectionB

Update collection metadata (name, description, variables)

ParametersJSON Schema
NameRequiredDescriptionDefault
infoNoCollection info
variablesNoCollection variables
collectionUidYesThe UID of the collection to update

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description carries the full burden of behavioral disclosure. It fails to specify whether the update is partial or full, whether variables are replaced or merged, or whether permissions are required. No side effects or reversibility are mentioned, leaving significant ambiguity for a mutation tool.

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, tightly worded sentence with no redundancy. Every word contributes to conveying the tool's purpose, making it highly scannable and efficient.

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?

Although the schema is well-documented, the tool has no annotations and no output schema. The description does not explain update semantics (e.g., whether variables replace the entire set), the necessity of the collectionUid parameter, or any response behavior. This leaves critical gaps for an agent to use the tool reliably.

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?

The schema provides 100% coverage of all three parameters, so the description does not need to repeat them. It adds no extra semantic value beyond naming the fields, which are already documented. A baseline score of 3 is appropriate since the schema handles the heavy lifting.

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 the tool's function with a specific verb ('update') and resource ('collection metadata'), listing the exact fields affected (name, description, variables). This distinguishes it from sibling tools like create_collection, delete_collection, and get_collection.

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?

The description provides no guidance on when to use this tool versus alternatives such as update_workspace or update_request, nor does it mention prerequisites like requiring an existing collection. It only implies usage from the action verb, offering no contextual exclusions or alternative recommendations.

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

update_environmentB

Update an existing environment

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoName of the environment
valuesNoUpdated values for the environment
environmentUidYesThe UID of the environment to update

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations, the description carries full responsibility for disclosing behavioral traits. However, it only states 'Update an existing environment' and does not mention side effects, permissions, whether all fields are overwritten or merged, or the result of the update. It adds little beyond what the tool name already implies.

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 single-sentence description is extremely concise and front-loaded, containing no filler or redundant wording. Every word earns its place, making it an efficient and well-structured minimal statement.

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?

Given the tool's complexity (a mutation with nested objects) and the absence of annotations and an output schema, the description is insufficient. It does not explain what happens on update (e.g., whether values replace existing ones, required fields, error conditions), leaving significant gaps for the agent to interpret the tool's behavior and expectations.

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?

The input schema covers 100% of the parameters, so the baseline is 3. The description itself does not add any parameter semantics, but the schema provides detailed descriptions for each field (e.g., 'The UID of the environment to update', 'Name of the environment'). The schema does the heavy lifting, and the description neither adds nor contradicts it.

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 phrase 'Update an existing environment' uses a specific verb ('update') and a specific resource ('environment'), clearly distinguishing it from sibling tools like create_environment, delete_environment, or get_environment. It unambiguously states the tool's action and target, meeting the highest standard for purpose clarity.

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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention, for example, that create_environment should be used for new environments or delete_environment for removing them. The agent is left to infer usage context solely from the tool name and sibling list.

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

update_requestA

Update an existing request in a collection

ParametersJSON Schema
NameRequiredDescriptionDefault
updatesYesFields to update
requestNameYesCurrent name of the request to update
collectionUidYesThe UID of the collection

TDQS

A3.7/5.0
Behavior2/5

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the operation without detailing mutation effects, partial update semantics, error handling, or required permissions. For a write operation, this is a significant gap.

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 that efficiently conveys the core purpose. There is no wasted content or redundancy.

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?

With three parameters including a nested 'updates' object and no output schema, the description is minimal. It explains the primary action but omits behavioral details such as return values or error scenarios. It is adequate but has clear gaps for a mutation tool.

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 100%, and the description adds no additional parameter semantics beyond what the schema already provides. The baseline of 3 is appropriate because the schema fully documents collectionUid, requestName, and updates.

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 the action ('Update') and the resource ('an existing request in a collection'), which distinguishes it from siblings like add_request and delete_request. It is 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.

Usage Guidelines4/5

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

The phrase 'existing request' provides clear context that this tool is for modifying already-created requests, implicitly differentiating it from add_request. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.

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

update_workspaceB

Update an existing workspace

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoNew name for the workspace
descriptionNoNew description for the workspace
workspaceIdYesThe ID of the workspace to update

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations, the description carries full responsibility for disclosing behavior. It only says 'existing', hinting that the workspace must already exist, but fails to mention partial update semantics, permissions, or side effects. No information is provided about whether fields not specified remain unchanged, or what errors might occur.

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 concise sentence with no filler words. It is well-structured and front-loaded for the core purpose, though it could benefit from a bit more detail without becoming verbose.

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?

For a mutation tool with no annotations and no output schema, the description is incomplete. It fails to explain that only name and description are updatable, that unspecified fields remain untouched, or any prerequisites or effects. The tool is simple but the description leaves important behavioral gaps.

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?

The input schema has 100% coverage with each parameter described. The description adds no additional parameter context, but the schema already documents workspaceId, name, and description clearly. Baseline of 3 applies since the schema does the heavy lifting.

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 clearly states the action ('Update') and the resource ('an existing workspace'), making the tool's purpose unambiguous. It distinguishes from sibling tools by resource type (workspace vs collections, environments, etc.). However, it provides no additional scope or qualifying detail beyond the name itself.

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 context is implied: use this when you need to modify an existing workspace. But no explicit guidance is given about when not to use it (e.g., if the workspace doesn't exist) or alternatives like create_workspace. The sibling list is available but no reference is made to it.

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. 19 tool updatesv1.0.3
    • First observedadd_request
    • First observedcreate_collection
    • First observedcreate_environment
    • First observedcreate_folder
    • First observedcreate_workspace
    • First observeddelete_collection
    • First observeddelete_environment
    • First observeddelete_folder
    • First observeddelete_request
    • First observedget_collection
    • First observedget_environment
    • First observedget_workspace
    • First observedlist_collections
    • First observedlist_environments
    • First observedlist_workspaces
    • First observedupdate_collection
    • First observedupdate_environment
    • First observedupdate_request
    • First observedupdate_workspace

TDQS

B3.3/5.0

Scored across 19 tools

Disambiguation5/5

Each tool targets a distinct resource and action. Workspaces, collections, requests, environments, and folders are cleanly separated, with no two tools appearing to do the same thing. The CRUD operations for each resource are unambiguous.

Naming Consistency4/5

The naming pattern is overwhelmingly consistent, using verb_noun in snake_case (e.g., list_workspaces, get_collection, update_environment). The only deviation is 'add_request' instead of 'create_request', which slightly disrupts the otherwise uniform create/update/delete pattern.

Tool Count4/5

At 19 tools, the count is slightly above the ideal 3-15 range but still reasonable for the breadth of Postman resources covered. Each tool has a clear purpose, and none feel redundant or unnecessary.

Completeness3/5

Collections and environments have full CRUD coverage, but requests lack read/list operations, folders only support create/delete, and workspaces miss delete. These gaps create minor dead ends that agents may need to work around when managing certain resources.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers