Skip to main content
Glama

Request secret

request_secret
Read-only

Ask the person for a secret only they have - an API token, a password, a licence key - without the value ever entering this conversation. If the organisation already stores a secret under the name, it answers status 'stored' with its sentinel. Otherwise it answers status 'waiting_for_person' with a link to the organisation's secrets page: give the person the link, ask them to store the secret there under exactly that name, and when they say it is done call request_secret again with the same name to get the sentinel. Never ask for, accept or repeat a secret value in the conversation; for a value nobody needs to know (a database password, a signing key) use create_secret instead. Read-only.

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": {
      "name": "<name>"
    },
    "name": "request_secret"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesThe name the secret is stored under, e.g. 'stripe-api-key' (at most 120 characters, one line).
descriptionNoOptional: what the secret is for and where the person finds it, to pass on with the link.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / additionalProperties
      Added value: +false
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

Although readOnlyHint already says this is a read-only operation, the description adds substantial behavioral detail beyond the annotation: it explains the two status responses, the sentinel value, the link to the organisation's secrets page, and the required re-call with the same name once the person says it is done. It also establishes the key safety rule that the secret value must never be asked for, accepted, or repeated in the conversation.

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 front-loaded with the core purpose and then walks through the response workflow in a compact, information-dense paragraph. It is longer than a simple tool description but every sentence carries relevant behavioral or safety information, with only minor redundancy in the closing 'Read-only.'

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

Completeness4/5

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

For a two-parameter tool with no output schema, the description does a good job explaining the meaningful return states and the user-interaction loop, including what to do with the link and when to call again. It does not cover error cases or permission requirements, but the essential behavior for correct invocation is present.

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 operational meaning to the name parameter by emphasizing that the secret must be stored under exactly that name and that the same name must be reused on the follow-up call. It does not add much about the optional description parameter, but the schema already documents it clearly.

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

Purpose5/5

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

The description states a specific verb and resource: ask the person for a secret they hold, such as an API token or password, while keeping the value out of the conversation. It also sharply distinguishes this tool from create_secret by explaining that create_secret is for values nobody needs to know, so an agent can choose correctly without opening sibling schemas.

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 gives explicit when-to-use guidance, including the two possible outcomes: status 'stored' when the organisation already has the secret, and 'waiting_for_person' when the person must store it. It also names the alternative create_secret and states the condition that selects it, which is exactly the routing information an agent needs.

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.