Skip to main content
Glama

Record a setup step

record_setup_step

Record the goal, a note, or a planned setup step. Administrator-only. agent_connected is owned by connection evidence; goal and note complete as recorded narrative, never assertions. Goals require application_id (or an Application goal step_id) and expected_outcome_revision. Project goal writes refuse with setup_requires_application: Setup is per Application; pass application_id. Goal completion requires a 20–2,000 Unicode character Application outcome; omitted or empty summary reuses only that Application outcome, and completion is refused if neither is valid. Accepted same-text CAS increments too and stale retries conflict. Application writes never read or change Project Overview. Plan datasources, solutions, apps and other independently created components. An Application holds one Hosted App. An app plan's subject.ref is accepted under an Application only when that Application can publish it: a published Application's own slug, or a slug no app holds under a draft. Any other is refused, and the refusal says which plan can bind. For a new app with no draft, plan its slug without application_id so the Application its first publication creates adopts it. Do not plan credentials, connector, schema or requests steps: the Project opens them itself once the datasource exists, and a Managed Project Database's requests step only once a Request is suggested against it; describe that work in the datasource step's summary instead. Recording kind ontology or questions with a datasource subject names that datasource's description work: the Project claims the step it already opened and answers with that step_id and state instead of appending a second one. A named ontology step becomes visible and required immediately. A named questions step stays hidden and optional until a human question exists, then becomes required. Connect the datasource first. An existing open observed step may be marked complete or failed, stored as asserted with your actor and summary, without changing component state or granting authority. A requests step cannot be asserted complete: it completes only when live state has no pending Request for its datasource and, except for the Managed Project Database, an approved, enabled Request. A members step cannot be asserted complete: it requires at least one non-Administrator person or invitation and an explicit MCP level decision for every Role holding one. A questions step cannot be asserted complete: it completes only when live state shows no human answer is owed. Every supported observed-kind assertion, complete or failed, requires summary as its reason. Close an unneeded entry that is still planned with state superseded and a summary giving the reason; this retires only that plan, leaves the summary it was authored with, and does not assert component completion or failure. Entries in any other state cannot be superseded here. The one exception is an open requests step. When the recorded goal needs no approved Request for that datasource (for example ad-hoc query access only), close it with state superseded and a summary giving the reason; do not assert it failed. The step is recorded as not needed, changes no Request, and is refused while a Request for that datasource awaits a decision. A later suggested Request opens a new Approve Requests round. A Data Access Point still requires an approved Request. A goal cannot be superseded: goals are recorded, never superseded, because a closed goal cannot be recorded again. Title limit 120 characters; summary limit 2000; at most 200 planned entries. Creation tools bind an explicit setup_step_id, otherwise the same session's oldest unbound plan of that kind matching its subject hint, otherwise a new entry. Planning a members step includes invitation_eligibility, the same note list_users reports including upgrade_url, when seat-taking invitations are restricted; the plan still succeeds. An offer Central did not confirm is not that restriction.

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

Input Schema

NameRequiredDescriptionDefault
kindYesgoal and note are recorded narrative. Plan independent components; datasource child steps and requests are opened by the Project. Naming kind ontology or questions claims the description step the Project opened for that datasource. Use an existing step_id to record supported assertions or supersede an unneeded plan. agent_connected belongs to connection evidence.
stateNoDefaults to complete for goal/note, planned for observed kinds; superseded requires an existing planned entry, or an open requests step, and a summary reason
titleNoAt most 120 characters
step_idNoExisting step UUID to update, assert or supersede
subjectNoSubject address: type, id (UUID), ref (provider, solution ID or app slug hint). A planned entry has no bound id.
summaryNoGoal completion requires a 20–2,000 Unicode character Application outcome. Omitted or empty summary reuses only that Application outcome; completion is refused if neither is valid. It is required for every observed-kind assertion and as the reason for superseding a planned entry or declining an open requests step, whose own summary is left as authored
application_idNoApplication UUID, required for a goal unless step_id selects an Application goal; a step_id inherits its persisted Application. A shared step keeps the Application it was opened for; steps this call opens record this one.
parent_step_idNoExisting parent step UUID
expected_overviewNoDormant Project goal parameter. Project goals are refused; Application goals use expected_outcome_revision
expected_revisionNoDormant Project goal parameter. Project goals are refused; Application goals use expected_outcome_revision
expected_outcome_revisionNoRequired nonnegative integer for Application goal completion, including same-text writes. Read the current revision with describe_application.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior5/5

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

The description adds far more than the annotations provide: stale same-text CAS conflicts, the exact refusal token setup_requires_application, which observed steps can and cannot be asserted complete, the effects of superseding (retiring only that plan, leaving the authored summary), entry limits (200 planned entries, 120/2000 character limits), and the fact that assertions grant no authority. This is unusually rich behavioral disclosure for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is a single dense block of jargon-heavy prose with abrupt transitions between rules and repeated restatements of the summary requirement. Many sentences carry necessary rules, but the lack of paragraphs or grouping by kind/state makes the definition hard to scan and the key routing information is not front-loaded beyond the first sentence.

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?

Given a multi-kind, multi-state tool with 11 parameters and no output schema, the description covers the state machine, refusal conditions, CAS behavior, and cross-tool dependencies (datasource connection, describe_application for revisions) thoroughly. It does not describe the success response shape or every kind's behavior equally, but an agent would have enough to call it safely in most cases.

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?

With 100% schema description coverage the baseline is 3, and the description earns an extra point by explaining semantics the schema does not: why application_id is required for goals, what subject.ref means for app plans, that expected_overview and expected_revision are dormant Project parameters, and how summary is reused or refused for goal completion. Minor gaps remain, such as parent_step_id, which is left to the schema.

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?

The opening sentence states a specific verb and resource ('Record the goal, a note, or a planned setup step') and adds an access constraint (Administrator-only). It does not name the read counterpart (get_setup_journal) or otherwise explicitly separate itself from sibling tools, but the core purpose is clear before the definition descends into edge cases.

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?

There is abundant conditional guidance ('Goals require application_id...', 'Do not plan credentials, connector, schema or requests steps', 'Connect the datasource first'), and it names describe_application for reading a revision. However it never states the straightforward when-to-use versus get_setup_journal or other setup-mutating siblings, and the guidance is embedded in an unstructured wall of text rather than presented as selection criteria.

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.

Resources