Claim and burn a secret deposited by another agent. Returns plaintext exactly once. A 404 means it was already consumed — treat that as a possible interception signal. Agents must use POST /api/agent/vault/:id/claim — never fetch the /secret/ HTML page.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The base64url decryption key. | |
| vaultId | Yes | The vault UUID to claim. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses key behaviors: returns plaintext exactly once, 404 means already consumed (possible interception), and the burn side-effect. It does not cover all error cases or auth requirements, but the most critical traits are transparently stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the main purpose, and every sentence adds critical information (action, return semantics, error handling, endpoint preference). No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema and annotations, the description covers return behavior, one important error condition with security implications, and the correct HTTP method. It omits other potential errors (e.g., wrong key, nonexistent vault) but is reasonably complete for a simple two-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters (key and vaultId), so the baseline is 3. The description adds no additional parameter-specific meaning beyond what the schema already provides, mentioning the endpoint but not the parameters directly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Claim and burn a secret deposited by another agent.' It also specifies the unique one-time return behavior, distinguishing it from siblings like burn_secret_immediately or check_secret_status. This is a specific, well-differentiated purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (when needing to claim a secret) and gives explicit usage instructions, such as using POST /api/agent/vault/:id/claim and never fetching the HTML page. It does not explicitly name alternative tools for other scenarios, but the guidance is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct operation: create, claim, burn, and check status. Although claim and burn both result in destruction, their contexts (deposited secret vs. own vault) are clearly separated by the descriptions.
All tools follow a consistent verb-first snake_case pattern (burn, check, claim, create). Minor variance in adverb/noun composition does not harm recognizability.
With 4 tools, the set is well-scoped for a focused one-time-secret service. Each tool covers a necessary part of the lifecycle without redundancy.
The lifecycle is fully covered: create, claim (read+consume), burn (destroy), and status check. No obvious missing operations for a one-time secret vault.
