Skip to main content
Glama
cirwel

UNITARES

by cirwel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

start_session

Register a new agent process and mint its identity, returning a client_session_id needed for later governed calls; use it to establish lineage or resume a verified same-process binding.

Instructions

Register this process-instance and mint its agent identity; keep the returned client_session_id for later calls. Call with force_new=true — a bare call with no ownership proof is defaulted to force_new or refused under strict identity, never resumed onto another process's uuid. parent_agent_id claims succession from an EXITED predecessor: naming a still-live parent is rejected as coincidental and the claim cleared, unless spawn_reason marks a dispatched child or a compaction continuation. Use identity to inspect or rename an existing binding. onboard is the canonical twin; this name adds a digest envelope. Read the uuid from agent_uuid; response_mode='full' keeps the raw payload under raw_governance.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameNoOptional COSMETIC display name; sets display_name only, never `agent_id` or `uuid`. Thread `uuid` across tools, not this.
resumeNoResume existing identity when a proof signal is present (continuity_token, agent_uuid, agent_id, client_session_id, or name).
agent_idNoUUID; leave unset for yourself.
force_newNoForce new identity creation.
thread_idNoExplicit thread ID to join (auto-derived from session if not provided)
model_typeNoOptional model type
client_hintNoClient hint string
orchestratedNoDeclare that a client_session_id is a thread-stable anchor provisioned by an orchestrator for a headless turn-child.
spawn_reasonNoWhy this fork was created. Registered reasons: subagent, dialectic_reviewer, dispatch, compaction, explicit, new_session.
initial_stateNoOptional bootstrap check-in payload.
response_modeNoVerbosity of the identity envelope.minimal
onboard_originNoAdapter-supplied observability label for the onboard entry path: agent, harness_backstop, or orchestrated_resume.
parent_agent_idNoUUID of predecessor agent (for fork lineage)
continuity_tokenNoSame-process rebind proof only; never a cross-process resume.
client_session_idNoBinding id for calls in this process; not a cross-process proof.
process_fingerprintNoOptional client-reported execution context: {host_id, pid, pid_start_time, transport, ppid?, tty?, anchor_path_hash?}.
trajectory_signatureNoTrajectory signature dict

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv3.1.0
    • changedInput schema / properties / agent_id / description
      Previous value: -"UNIQUE agent identifier; optional when session-bound (auto-injected)."New value: +"UUID; leave unset for yourself."
    • changedInput schema / properties / client_session_id / description
      Previous value: -"In-session binding id from start_session()/identity(); pass it on same-process calls. Not a cross-process proof."New value: +"Binding id for calls in this process; not a cross-process proof."
    • changedInput schema / properties / continuity_token / description
      Previous value: -"Ownership proof from onboard()/identity(), for same-live-process rebinds only. Not a cross-process resume credential."New value: +"Same-process rebind proof only; never a cross-process resume."
  2. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations only supply generic hints (readOnly=false, idempotent=false, destructive=false). The description goes well beyond them, disclosing the force_new defaulting/refusal path under strict identity, the parent_agent_id succession rule (live parent rejected as coincidental), and response_mode='full' retaining the raw payload under raw_governance.

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

Conciseness3/5

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

Front-loaded with the purpose, but the body is a chain of semicolon-joined clauses mixing identity rules, lineage rules, and response modes, making it hard to scan. Information density is high, but structure and readability suffer.

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 17-param, zero-required identity bootstrap with no output schema, the description covers the essential call path and the critical failure modes (defaulting, refusal, lineage rejection). It omits the response envelope's full contents, but names the two key fields to retain (client_session_id, agent_uuid).

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 baseline is 3. The description still adds meaning the one-line schema entries lack: the interactive semantics of force_new (defaulted-or-refused, never resumed onto another uuid), the parent_agent_id validation outcome, and where the uuid surfaces (agent_uuid).

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?

States a specific verb+resource: 'Register this process-instance and mint its agent identity,' and names siblings it differs from ('Use identity to inspect or rename an existing binding', 'onboard is the canonical twin'). The dense jargon slightly obscures the plain purpose, but the core action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete routing: use force_new=true, a bare call is defaulted or refused, use identity for inspect/rename, and onboard is the canonical twin. Covers when-to-use and some when-not, though it never gives a clean 'prefer onboard unless X' rule.

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

Deploy Server

Other Tools