Skip to main content
Glama
cirwel

UNITARES

by cirwel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

start_session

Register a process instance, mint its agent identity, and return a client_session_id for subsequent calls. Use force_new=true for new identities; resume requires valid ownership proof.

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

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) and …
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. Changed1 schema field changedv3.4.0
    • changedInput schema / properties / resume / description
      Previous value: -"Resume existing identity when a proof signal is present (continuity_token, agent_uuid, agent_id, client_session_id, or name)."New value: +"Resume existing identity when a proof signal is present (continuity_token, agent_uuid, agent_id, client_session_id, or name) and …"
  2. 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."
  3. First observed

TDQS

A3.9/5.0
Behavior5/5

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

Without relying on annotations, the description discloses non-obvious behavior: a bare call is defaulted to force_new or refused under strict identity, a still-live parent claim is rejected as coincidental and cleared, and response_mode='full' retains the raw payload. That is substantially more than the annotations (readOnly=false, idempotent=false) convey.

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?

The primary purpose is front-loaded, but the body is a dense run-on of clauses with unexplained jargon ('digest envelope', 'raw_governance', 'coincidental') and references 'agent_uuid' (an output field, not a param) without setup. Much is information-rich, yet parsing cost is high.

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, no-output-schema identity tool this captures the critical behaviors (identity minting, force_new, succession, response envelope) that an agent needs. It does not address numerous auxiliary params, but the schema documents them fully, so little is genuinely 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 baseline is 3, and the description adds genuine meaning for key params: it explains what force_new's default fallback does, the succession semantics of parent_agent_id, and the effect of response_mode='full'. Several other params (thread_id, trajectory_signature, process_fingerprint) get no added explanation, keeping this from a 5.

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 states a concrete verb+resource ('Register this process-instance and mint its agent identity') and the two related tools (identity, onboard) are named. However, 'this name adds a digest envelope' and the near-synonymy with onboard make it hard to tell precisely which tool an agent should reach for at bootstrap time.

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?

It gives real conditional guidance (force_new coercion, parent_agent_id succession rules, 'use identity to inspect or rename'). But the routing sentence 'onboard is the canonical twin; this name adds a digest envelope' is opaque and leaves the agent unsure whether onboard or start_session is the correct entry point.

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