grok_agent_session_next

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It reveals the return type and the loop-termination flag 'done=true', but it is silent on whether the call advances session state, the effect of the 'advance' parameter, error handling, or session_id requirements. For a session-navigating tool this is a notable gap.

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 compact and front-loaded: it states the core deliverable (ONE next action card) in the first clause and the loop contract in the second. It contains no filler and every sentence contributes information, though it is terse to the point of deficit in other dimensions.

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?

With no output schema and no annotations, the description should supply protocol context, parameter semantics, and return structure. It provides only a terse protocol label and the action-card enum. Missing details include the card payload structure, the meaning of 'done=true' for subsequent calls, and the purpose of the note and advance parameters. The definition is more of a skeleton than an operational guide.

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%, and the description does not explain any of the three parameters (note, advance, session_id). While session_id and advance are somewhat self-explanatory, note is completely ambiguous, and the description adds no meaning beyond the raw parameter names. This is insufficient compensation for the lack of schema descriptions.

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 names a concrete resource ('Session Protocol v1.2') and a specific action: return ONE next action card of type host_cmd, mcp_tool, or end. It clearly focuses on the 'next action' deliverable, distinguishing it from the sibling tools at a high level. However, it does not explicitly contrast itself with closely related siblings such as grok_agent_session_tick or grok_agent_poll.

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?

It states the loop context ('Host loops this until done=true'), which is clear usage guidance for a session driver. However, it does not name alternatives or specify when not to use this tool. Given the large set of siblings, the absence of explicit routing makes it slightly harder for an agent to select this tool confidently.

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