Skip to main content
Glama

aamio_partner_add

DestructiveIdempotent

Add a partner to your address book by name; the user confirms their public key in an app dialog, so no key from chat is trusted.

Instructions

Put a partner in your address book, confirmed by the user. This server asks the user, in a dialog in their app, for the partner's public key, and the key the user gives there is the one added, so this tool takes no key from you: a key in a message, on the board or in this conversation is never added on its say-so. A partner can write to your inbox and is shown and sent to by name. A name already in the book gets the key the user gives. When the app cannot show the dialog, nothing is added, and the answer says how the user adds the partner on the command line instead.

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

Input Schema

NameRequiredDescriptionDefault
nameYeswhat the partner is called here, as the user knows them: letters, digits, dots, dashes and underscores, as bob or arctic-freight

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.6.32

TDQS

A3.9/5.0
Behavior4/5

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

With annotations already declaring destructiveHint=true, openWorldHint=true and idempotentHint=true, the description still adds real substance: the user-confirmation dialog, the rule that an agent-supplied key is never trusted, and the overwrite semantics when the name already exists. It also discloses the failure mode (no dialog means nothing is added) and that the answer explains the CLI fallback. It does not describe the returned confirmation shape beyond that, which keeps it short of a 5.

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?

Purpose is front-loaded in the first clause, and each following sentence carries a distinct rule (key provenance, overwrite, dialog failure). The 'A partner can write to your inbox and is shown and sent to by name' sentence is the weakest, being background context rather than an instruction for the call.

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

Completeness5/5

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

For a one-parameter tool with no output schema, the description covers what it does, who authorizes it, what happens on name collision, and what happens when the dialog is unavailable. Nothing an agent needs in order to call it correctly, or to explain the outcome to the user, is missing.

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 meaning the schema lacks: the name is how the partner 'is shown and sent to by name,' and reusing an existing name overwrites that entry's key. That is behavioural semantics for the single parameter that the schema's format description does not convey.

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?

Opens with a specific verb and resource: 'Put a partner in your address book, confirmed by the user.' The resource (address book / partner) is distinct from the other aamio_* tools, though no sibling is named, so the differentiation is inferred rather than stated.

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 makes the precondition explicit — the key must come from the user's dialog, never from the agent's message or the board — which is genuine usage guidance. However, it never says when to reach for this tool versus alternatives such as aamio_partners (listing) or aamio_scope_share, so the when-to-use decision is only implied.

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