# Key shapes

A key decides what a connection may see and do. Which tools it is listed follows from its key shape, and the count is not the same for every key: that is why the docs, a directory listing and an agent’s own answer can each give a different number, and each can be right. This page says what each shape is listed and which of the tools may change something. Every tool in the [MCP reference](/docs/mcp) links here.

## The three kinds

**Read-only.** It reads the map, the findings and the work, and changes nothing on the map without a person. A new key starts here. The table below counts the few tools a read-only shape may still call that change something, such as suggesting a feature or, where the workspace has an action policy, asking for an action. The published demo key and a directory reviewer’s key are read-only too.

**Acts with approval.** An admin chose it for the key. Taking a signal and recording work apply at once, except a resolution of not_an_issue or wont_fix, which waits for a person; a change that needs a person, such as a finding’s status, an answer about a column’s identity or a draft, waits for one.

**Autonomous.** An admin chose it for the key. Its changes apply at once and every action is logged. It reads the whole map unless an admin limited it, and it may upload only with the consent an admin gave it.

The shapes below are the typical keys of these three kinds, with the limits and consents an admin can add.

## Every key shape

Which tools a connection is listed depends on its key and on what its workspace has switched on. The rows below are typical keys, each served its own list: between 14 and 36 of the tools in this reference. The count is the number `tools/list` returns for that typical key, with live checks off except in Maplith’s own workspace, and wake-ups on for every row of a customer’s key. Only autonomous keys are listed the wake-up tools: in a workspace where wake-ups are off, which is the default, an autonomous key is listed three fewer than its row, without `set_wake_subscription`, `remove_wake_subscription` and `wake_subscription`. Where an admin binds a key to a live check, and for a member’s own reporting connection, tools come on top of the row, so a key’s list can differ from its row; each tool’s Who sees it says when. `get_map_overview`’s `your_key.shape` says whether your key is read-only, acts with approval, is autonomous or proposes, which is the nearest row. The in-app assistant holds no key and is served its own list of 13.

| Key shape | Kind | How a key gets it | Tools listed | Of which change something |
|---|---|---|---|---|
| The published demo key | Read-only | Anyone may use it, on a fictional company’s map. It reads and changes nothing of yours. | 14 | 0 |
| A directory reviewer’s key | Read-only | Given to the reviewer of a directory listing: the demo key, locked. | 14 | 0 |
| A reviewer’s key in the review sandbox | Acts with approval | Given to a directory reviewer in the review sandbox: it acts with approval, may upload, and the sandbox holds fixed policies for it. | 30 | 14 |
| Read-only, strict | Read-only | The default for a new key: it is listed the tools that read. An admin who binds it to a live check adds report_observation, which records an observation and can raise or clear that rule’s signal. | 15 | 0 |
| Read-only, older keys | Read-only | A read-only key made before keys became strict; it is also listed the join review, suggestion and request tools. | 19 | 2 |
| Read-only, workspace with an action policy | Read-only | A read-only key in a workspace where an admin set an action policy (older connections). | 21 | 5 |
| Acts with approval | Acts with approval | An admin chose it for the key: finding-status changes, field-identity answers, requests for a decision and drafts wait for a person; taking a signal and recording work apply at once, and some tools are refused to it (each tool says which). | 28 | 12 |
| Autonomous, whole map | Autonomous | An admin chose it for the key: its changes apply at once, every action is logged, and it reads the whole map. | 32 | 16 |
| Autonomous, part of the map | Autonomous | Autonomous, and an admin limited the key to named domains or objects. | 30 | 14 |
| Autonomous, with upload consent | Autonomous | Autonomous, and an admin allowed the key to upload exports and start a scan. | 34 | 18 |
| Autonomous, Maplith’s own workspace | Autonomous | The widest key: autonomous, with uploads and live checks on, in Maplith’s own workspace. It sees every tool of the reference. | 36 | 19 |

## What may change something

19 of the 36 tools may change something. Nothing happens in your own systems through any of them; they change what Maplith holds, or ask for a decision. Each row says what the tool changes, how a person is involved, and which of the 11 key shapes list it.

| Tool | What it changes | How a person is involved | Key shapes that list it |
|---|---|---|---|
| [`correct_source_system`](/docs/mcp#tool-correct_source_system) | Re-homes uploaded files under another system name. It never removes anything from the map, and only an autonomous key that reads the whole map can call it. | No person decides each call: it applies when called, and the call is logged. | Acts with approval (all 2); Autonomous (all 4) |
| [`answer_question`](/docs/mcp#tool-answer_question) | Records the answer to a question Maplith asked (a column’s identity, a row key, a dialect, which copied file is the original). A field identity answer from a key that acts with approval waits for a person, and a person’s answer always stands. | An autonomous key applies it at once. A key that acts with approval waits for a person to decide, in the cases named above. | Acts with approval (all 2); Autonomous (all 4) |
| [`submit_sources`](/docs/mcp#tool-submit_sources) | Stores the uploaded files in the workspace until they are built into the map; an upload that is not built within 24 hours is deleted. | No person decides each call: an admin has to allow it on the key first (upload consent). | Acts with approval (1 of 2: A reviewer’s key in the review sandbox); Autonomous (2 of 4: Autonomous, with upload consent; Autonomous, Maplith’s own workspace) |
| [`build_map`](/docs/mcp#tool-build_map) | Starts a scan of the submitted upload and the current connections, which builds or rebuilds the map. | No person decides each call: an admin has to allow it on the key first (upload consent). | Acts with approval (1 of 2: A reviewer’s key in the review sandbox); Autonomous (2 of 4: Autonomous, with upload consent; Autonomous, Maplith’s own workspace) |
| [`configure_metric`](/docs/mcp#tool-configure_metric) | Starts, changes or stops tracking a metric’s value, and sets its threshold. Only aggregates are kept, and recorded values stay when tracking stops. Only an autonomous key can call it. | No person decides each call: it applies when called, and the call is logged. | Acts with approval (all 2); Autonomous (all 4) |
| [`state_relationships`](/docs/mcp#tool-state_relationships) | Writes the stated relationships for future scans to test. Each scan tests every statement against the data and turns one that does not hold into a question for your human. Only an autonomous key that reads the whole map can call it. | No person decides each call: it applies when called, and the call is logged. | Autonomous (3 of 4: Autonomous, whole map; Autonomous, with upload consent; Autonomous, Maplith’s own workspace) |
| [`join_review`](/docs/mcp#tool-join_review) | Opens a review of a join, or adds counts to one. It changes nothing on the map by itself: a person decides, unless a key that may act reports counts that agree on a review Maplith opened, which marks that join tested. | A person decides: the tool only asks, drafts or opens a review. | Read-only (2 of 5: Read-only, older keys; Read-only, workspace with an action policy); Acts with approval (all 2); Autonomous (all 4) |
| [`update_finding_status`](/docs/mcp#tool-update_finding_status) | Changes a finding’s status to open, planned, automated or dismissed. The change is logged. | An autonomous key applies it at once. A key that acts with approval waits for a person to decide, in the cases named above. | Acts with approval (all 2); Autonomous (all 4) |
| [`register_automation`](/docs/mcp#tool-register_automation) | Adds or updates an entry in the map. It never runs or connects to the automation, and an entry a person confirmed keeps its name, team and objects. Only an autonomous key can call it. | No person decides each call: it applies when called, and the call is logged. | Acts with approval (all 2); Autonomous (all 4) |
| [`draft_playbook`](/docs/mcp#tool-draft_playbook) | Saves a draft playbook, or a person’s stated manual time, and can put a new draft in a workflow of the workspace. A draft is not in use until an admin approves it, and an agent cannot approve, edit or delete one, or take one out of a workflow. | A person decides: the tool only asks, drafts or opens a review. | Acts with approval (all 2); Autonomous (3 of 4: Autonomous, whole map; Autonomous, with upload consent; Autonomous, Maplith’s own workspace) |
| [`report_observation`](/docs/mcp#tool-report_observation) | Records what you observed for a live check, which raises or clears the rule’s own signal. Maplith checks each group against the rule’s conditions and refuses a report that does not fit the contract. | No person decides each call: it applies when called, and the call is logged. | Listed by a setting of the workspace |
| [`take_signal`](/docs/mcp#tool-take_signal) | Moves a signal from open to in progress, held by your key for up to 72 hours, or plans it for later. Taking it again renews the hold. | No person decides each call: it applies when called, and the call is logged. | Acts with approval (all 2); Autonomous (all 4) |
| [`record_action`](/docs/mcp#tool-record_action) | Records finished work and its outcome, and closes or hands over a signal. It changes nothing in your human’s systems and starts no scan. A resolution of not an issue or won’t fix waits for a person under a key that acts with approval, unless the key is a delegate. | An autonomous key applies it at once. A key that acts with approval waits for a person to decide, in the cases named above. | Read-only (1 of 5: Read-only, workspace with an action policy); Acts with approval (all 2); Autonomous (all 4) |
| [`request_action`](/docs/mcp#tool-request_action) | Records a request and answers it from the key’s action policy: allowed (with a grant to redeem where Maplith signs grants), denied, or pending until an admin decides. Maplith never acts in your human’s systems itself. | The key’s action policy answers: allowed, denied, or pending until an admin decides. | Read-only (2 of 5: Read-only, older keys; Read-only, workspace with an action policy); Acts with approval (all 2); Autonomous (all 4) |
| [`redeem_action_grant`](/docs/mcp#tool-redeem_action_grant) | Spends a single-use grant: the first redemption marks it used, and every later attempt is refused. The action itself happens in your human’s system, not here. | Maplith changes nothing in your human’s systems: the agent does that work with its own credentials, only after an allowed answer. | Read-only (1 of 5: Read-only, workspace with an action policy); Acts with approval (all 2); Autonomous (all 4) |
| [`suggest_feature`](/docs/mcp#tool-suggest_feature) | Sends a suggestion or a bug report to Maplith. The text leaves the workspace, so it carries capability only: no records, values, names, credentials or identifiers. | No person decides each call: it applies when called, and the call is logged. | Read-only (2 of 5: Read-only, older keys; Read-only, workspace with an action policy); Acts with approval (all 2); Autonomous (all 4) |
| [`set_wake_subscription`](/docs/mcp#tool-set_wake_subscription) | Creates or changes one of your key’s wake endpoints and its filter. A new endpoint, a rotated secret and a test each send one signed test wake-up to the address you give. Only an autonomous key can call it. | No person decides each call: it applies when called, and the call is logged. | Listed by a setting of the workspace |
| [`remove_wake_subscription`](/docs/mcp#tool-remove_wake_subscription) | Removes the endpoint with its delivery log and revokes its secret; nothing more is sent to it. It is refused for an endpoint a person set up or limited. | No person decides each call: it applies when called, and the call is logged. | Listed by a setting of the workspace |
| [`wake_subscription`](/docs/mcp#tool-wake_subscription) | op set creates or changes one of your key’s wake endpoints and its filter; a new endpoint, a rotated secret and a test each send one signed test wake-up to the address you give. op remove removes an endpoint with its delivery log and revokes its secret, and is refused for one a person set up or limited. Only an autonomous key can call it. | No person decides each call: it applies when called, and the call is logged. | Listed by a setting of the workspace |

## Upload consent

Uploading exports and starting a scan are changes that no person decides call by call. An admin allows them on the key first, under Sources › Agents, and a key without that consent is not listed them. The tools are [`submit_sources`](/docs/mcp#tool-submit_sources) and [`build_map`](/docs/mcp#tool-build_map). They are listed to these key shapes: A reviewer’s key in the review sandbox; Autonomous, with upload consent; Autonomous, Maplith’s own workspace.

## Part of the map

An admin can limit an autonomous key to named domains or objects. That shape (Autonomous, part of the map) is listed 30 tools, 2 fewer than the whole-map shape (Autonomous, whole map, 32). The tools it is not listed are [`draft_playbook`](/docs/mcp#tool-draft_playbook) and [`state_relationships`](/docs/mcp#tool-state_relationships). Every other tool it is listed answers within the part of the map the key is limited to, except `correct_source_system`: it is listed, but only a whole-map key may call it.

## Where to go next

- [Agent keys and policies](/docs/agent-keys): how an admin creates a key and sets what it may do.
- [Connect your own agent](/docs/own-agent): signing in, the key and the first prompt.
- [Work the loop](/docs/work-the-loop): the calls a key that may act makes, from a task to a record of the work.
- [Words](/docs/words): the names used here.
