Skip to main content
Glama
Sign In
gograph

gograph

by ozgurcd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

gograph_session_create

Start a telemetry audit session at the beginning of a multi-step coding task, then use the returned session ID to track compliance and tool success across later requests.

Instructions

Start a telemetry audit session for tracking agent compliance and tool success metrics. Writes only regular, repository-confined session state under .gograph/sessions and refuses linked storage; MCP annotations mark it mutating and non-idempotent. No prerequisites once the MCP server is running. WHEN TO USE: Call once at the start of a multi-step coding task to track your work. Pass the returned ID as session_id on this caller's later requests. Independent callers may create alongside other active sessions. RETURNS: Message with the caller session ID.

Input Schema

NameRequiredDescriptionDefault
rootNoAbsolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.
intentionNoTechnical rationale, required for analytical calls selecting an active session.
session_idNoCaller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.
custom_wordNoOptional custom word prefix to incorporate in the timestamped session ID (e.g. 'implement_feature')

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.7.18
    • addedInput schema / properties / intention
      Added value: +{
+  "description": "Technical rationale, required for analytical calls selecting an active session.",
+  "type": "string"
+}
    • addedInput schema / properties / root
      Added value: +{
+  "description": "Absolute path of the checkout you are working in (your cwd or git worktree). Must be this server's repository or one of its git worktrees; the answer then comes from that checkout's own graph. A path elsewhere is refused. Alias: cwd. Omit only when the configured checkout is the one you mean.",
+  "type": "string"
+}
    • addedInput schema / properties / session_id
      Added value: +{
+  "description": "Caller selector returned by session_create. Omission means an independent caller; never inherits server environment or another caller's session.",
+  "type": "string"
+}
  2. Added

TDQS

A3.9/5.0
Behavior4/5

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

Beyond the annotations, the description discloses where state lands (regular, repository-confined files under .gograph/sessions) and a concrete refusal behavior (linked storage is rejected), which are real operational traits an agent cannot get from structured fields. It also states the returned session ID must be passed on later requests. The sentence 'MCP annotations mark it mutating and non-idempotent' merely restates readOnlyHint=false and idempotentHint=false, adding no new information.

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?

The definition is front-loaded with purpose, then scoped by WHEN TO USE and RETURNS labels, which makes it easy to scan. One sentence is pure redundancy ('MCP annotations mark it mutating and non-idempotent') and could be cut without loss. Overall it is appropriately sized for a session-creation tool.

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?

With no output schema, the description correctly supplies return information ('Message with the caller session ID'), and all four optional parameters are covered by the schema. Storage location, refusal behavior, and the session-ID handoff are all present. It lacks any statement about session lifetime or how the session terminates, which matters for a create tool that has dedicated end/cleanup siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains root, intention, session_id, and custom_word in detail. The description adds only one piece of parameter meaning beyond that, tying the returned ID to the session_id field on subsequent calls. It says nothing about the custom_word prefix or the intention rationale, so it neither compensates for nor enriches the schema meaningfully.

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 description opens with a specific verb and resource: 'Start a telemetry audit session for tracking agent compliance and tool success metrics,' which is far more informative than the bare name. It does not explicitly name its lifecycle siblings (gograph_session_end, gograph_session_audit, gograph_session_cleanup), so an agent must infer the entry-point role from the 'Call once at the start' guidance rather than from a direct contrast.

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?

'WHEN TO USE: Call once at the start of a multi-step coding task' plus 'No prerequisites once the MCP server is running' gives clear triggering context and preconditions. It also clarifies that independent callers may create sessions alongside existing ones. It stops short of an explicit exclusion (e.g., do not create for single-shot queries) or of naming the corresponding end/audit tools, so it is strong but not fully routable.

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