Skip to main content
Glama

update_secret_reference

DestructiveIdempotent

Update fields on a Portkey Secret Reference, such as its name, path, tags, or auth config. Use it to change secret metadata, merge manager credentials, or replace workspace access rules.

Instructions

Update at least one selected field on a Secret Reference. auth_config is merged into the existing manager-specific configuration. allowed_workspaces replaces all workspace mappings and sets allow_all_workspaces=false; allow_all_workspaces=true removes workspace-specific mappings. Credential values are sent to Portkey and exposed to the MCP transcript.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

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

Input Schema

NameRequiredDescriptionDefault
idYesSecret Reference UUID or slug
nameNoNew human-readable name
tagsNoReplacement string key-value tags, or null to clear them
secret_keyNoNew key within a structured secret, or null to use the whole value
auth_configNoProvide at least one changed authentication field to merge into the existing configuration; choose one AWS, Azure, or HashiCorp field family and do not mix families
descriptionNoNew description, or null to clear it
secret_pathNoNew path of the secret in the external secret manager
allowed_workspacesNoReplacement list of workspace UUIDs or slugs allowed to use this reference; supplying it sets allow_all_workspaces=false
allow_all_workspacesNoWhether every workspace may use this reference; cannot be true with allowed_workspaces

Output Schema

NameRequiredDescriptionDefault
okYesCall succeeded
dataNoSuccess payload
errorNoFailure details

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.16.5
    • changedOutput schema / properties / data / description
      Previous value: -"Structured success payload when ok is true"New value: +"Success payload"
    • changedOutput schema / properties / error / description
      Previous value: -"Structured error payload when ok is false"New value: +"Failure details"
    • changedOutput schema / properties / error / properties / details / description
      Previous value: -"Optional structured error details"New value: +"Extra error details"
    • changedOutput schema / properties / error / properties / message / description
      Previous value: -"Human-readable error message"New value: +"Error message"
    • changedOutput schema / properties / ok / description
      Previous value: -"Whether the tool call succeeded and returned structured data"New value: +"Call succeeded"
  2. Changed2 schema fields changedv1.0.9
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  3. Changed1 schema field changedv0.12.2
    • changedInput schema / properties / auth_config / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "aws_access_key_id": {
      -        "description": "AWS access key ID; required when aws_auth_type is accessKey",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "aws_auth_type": {
      -        "description": "AWS authentication mode: accessKey uses a key pair, assumedRole uses an IAM role, and serviceRole uses the runtime workload identity",
      -        "enum": [
      -          "accessKey",
      -          "assumedRole",
      -          "serviceRole"
      -        ],
      -        "type": "string"
      -      },
      -      "aws_external_id": {
      -        "anyOf": [
      -          {
      -            "type": "string"
      -          },
      -          {
      -            "type": "null"
      -          }
      -        ],
      -        "description": "Optional external ID required by the target IAM role"
      -      },
      -      "aws_region": {
      -        "description": "AWS region containing the secret, for example us-east-1",
      -        "type": "string"
      -      },
      -      "aws_role_arn": {
      -        "description": "IAM role ARN to assume; required when aws_auth_type is assumedRole",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "aws_secret_access_key": {
      -        "description": "AWS secret access key; required when aws_auth_type is accessKey and exposed to the MCP transcript",
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "azure_auth_mode": {
      -        "description": "Azure authentication mode: entra uses a client secret, managed uses managed identity, and default uses the runtime credential chain",
      -        "enum": [
      -          "entra",
      -          "managed",
      -          "default"
      -        ],
      -        "type": "string"
      -      },
      -      "azure_entra_client_id": {
      -        "description": "Microsoft Entra application client ID; required for entra authentication",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "azure_entra_client_secret": {
      -        "description": "Microsoft Entra client secret; required for entra authentication and exposed to the MCP transcript",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "azure_entra_tenant_id": {
      -        "description": "Microsoft Entra tenant ID; required for entra authentication",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "azure_managed_client_id": {
      -        "description": "Optional client ID of a user-assigned managed identity; omit for the system-assigned identity",
      -        "type": "string"
      -      },
      -      "azure_vault_url": {
      -        "description": "Azure Key Vault URL, for example https://example.vault.azure.net",
      -        "format": "uri",
      -        "type": "string"
      -      }
      -    },
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "properties": {
      -      "vault_addr": {
      -        "description": "Base URL of the HashiCorp Vault server",
      -        "format": "uri",
      -        "type": "string"
      -      },
      -      "vault_auth_type": {
      -        "description": "HashiCorp Vault authentication mode: token, AppRole, or Kubernetes",
      -        "enum": [
      -          "token",
      -          "approle",
      -          "kubernetes"
      -        ],
      -        "type": "string"
      -      },
      -      "vault_namespace": {
      -        "description": "Optional HashiCorp Vault Enterprise namespace",
      -        "type": "string"
      -      },
      -      "vault_role": {
      -        "description": "HashiCorp Vault Kubernetes auth role name",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "vault_role_id": {
      -        "description": "HashiCorp Vault AppRole role ID; required for approle authentication",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "vault_secret_id": {
      -        "description": "HashiCorp Vault AppRole secret ID; required for approle authentication and exposed to the MCP transcript",
      -        "minLength": 1,
      -        "type": "string"
      -      },
      -      "vault_token": {
      -        "description": "HashiCorp Vault token; required for token authentication and exposed to the MCP transcript",
      -        "minLength": 1,
      -        "type": "string"
      -      }
      -    },
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "aws_access_key_id": {
      +        "description": "AWS access key ID; required when aws_auth_type is accessKey",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "aws_auth_type": {
      +        "description": "AWS authentication mode: accessKey uses a key pair, assumedRole uses an IAM role, and serviceRole uses the runtime workload identity",
      +        "enum": [
      +          "accessKey",
      +          "assumedRole",
      +          "serviceRole"
      +        ],
      +        "type": "string"
      +      },
      +      "aws_external_id": {
      +        "description": "Optional external ID required by the target IAM role",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "aws_region": {
      +        "description": "AWS region containing the secret, for example us-east-1",
      +        "type": "string"
      +      },
      +      "aws_role_arn": {
      +        "description": "IAM role ARN to assume; required when aws_auth_type is assumedRole",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "aws_secret_access_key": {
      +        "description": "AWS secret access key; required when aws_auth_type is accessKey and exposed to the MCP transcript",
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "azure_auth_mode": {
      +        "description": "Azure authentication mode: entra uses a client secret, managed uses managed identity, and default uses the runtime credential chain",
      +        "enum": [
      +          "entra",
      +          "managed",
      +          "default"
      +        ],
      +        "type": "string"
      +      },
      +      "azure_entra_client_id": {
      +        "description": "Microsoft Entra application client ID; required for entra authentication",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "azure_entra_client_secret": {
      +        "description": "Microsoft Entra client secret; required for entra authentication and exposed to the MCP transcript",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "azure_entra_tenant_id": {
      +        "description": "Microsoft Entra tenant ID; required for entra authentication",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "azure_managed_client_id": {
      +        "description": "Optional client ID of a user-assigned managed identity; omit for the system-assigned identity",
      +        "type": "string"
      +      },
      +      "azure_vault_url": {
      +        "description": "Azure Key Vault URL, for example https://example.vault.azure.net",
      +        "format": "uri",
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "properties": {
      +      "vault_addr": {
      +        "description": "Base URL of the HashiCorp Vault server",
      +        "format": "uri",
      +        "type": "string"
      +      },
      +      "vault_auth_type": {
      +        "description": "HashiCorp Vault authentication mode: token, AppRole, or Kubernetes",
      +        "enum": [
      +          "token",
      +          "approle",
      +          "kubernetes"
      +        ],
      +        "type": "string"
      +      },
      +      "vault_namespace": {
      +        "description": "Optional HashiCorp Vault Enterprise namespace",
      +        "type": "string"
      +      },
      +      "vault_role": {
      +        "description": "HashiCorp Vault Kubernetes auth role name",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "vault_role_id": {
      +        "description": "HashiCorp Vault AppRole role ID; required for approle authentication",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "vault_secret_id": {
      +        "description": "HashiCorp Vault AppRole secret ID; required for approle authentication and exposed to the MCP transcript",
      +        "minLength": 1,
      +        "type": "string"
      +      },
      +      "vault_token": {
      +        "description": "HashiCorp Vault token; required for token authentication and exposed to the MCP transcript",
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  }
      +]
  4. Addedv0.5.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds real value: it discloses that auth_config is merged while allowed_workspaces replaces all mappings, that allow_all_workspaces=true wipes workspace-specific mappings, and that credential values are sent to Portkey and exposed in the MCP transcript. That last point is a genuinely important side effect an agent would not learn from annotations alone.

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?

Four tight sentences, front-loaded with the core action, then the two non-obvious field semantics, then the security warning. No filler and nothing buried.

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?

With an output schema present, return values need no explanation, and the annotations cover the safety profile. The description fills the remaining gaps an agent needs: partial-update requirement, merge/replace semantics, and credential exposure.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint absent from the schema: at least one field must actually change, and it clarifies the merge-vs-replace behavior of auth_config versus allowed_workspaces. It largely consolidates rather than extends schema text, which keeps it from a 5.

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?

States a specific verb and resource ("Update ... a Secret Reference") and adds the partial-update constraint ("at least one selected field"), which distinguishes it from a full replace. It does not explicitly name create/delete/get siblings, but the verb+resource pairing is unambiguous against them.

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 mutation semantics rather than stated: the description explains what happens when certain fields are supplied but never says when to choose this tool over create_secret_reference or delete_secret_reference, nor what prerequisites (permissions, existing reference) are needed.

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

Deploy Server

Other Tools