grok_agent_session_tickTrack coding-agent session progress and budget, returning steps left, remaining budget, and force_end; submit tool_used or step_done to decrement budget.
Session Protocol v1.2: compact progress + budget. Returns step, steps_left, budget_remaining, force_end. Pass tool_used/step_done to count budget. verbose default false.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | ||
| verbose | No | ||
| step_done | No | ||
| tool_used | No | ||
| session_id | No |
Changes observed during successful MCP inspections.
v0.26.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by naming the return fields (step, steps_left, budget_remaining, force_end) and the budget-counting trigger, but it does not explain what force_end implies or how state is mutated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a tight, front-loaded cluster of sentences with no filler: protocol banner, return contract, usage hint, and default note. It is efficient, though the extreme terseness borders on cryptic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a stateful session/budget tool with 5 undocumented parameters and no output schema, the description is too thin. It lists return field names but not their meaning, omits job_id vs session_id, and never explains how ticks relate to the surrounding session lifecycle tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 5 parameters, so the description must carry the burden. It covers only three of them (tool_used/step_done semantics, verbose default false) and leaves the two identifier parameters, job_id and session_id, completely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description frames the tool as 'Session Protocol v1.2: compact progress + budget' and lists return fields, so an agent can infer it reports session step/budget state. However, the verb 'tick' is jargon and the description never differentiates this from siblings like grok_agent_session_next or grok_agent_session_begin, leaving the exact purpose somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Pass tool_used/step_done to count budget' implies usage occurs after completing a step, which is a partial usage cue. But there is no explicit when-to-use vs session_begin/session_next/session_end, and no prerequisites or exclusion conditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.