autocode

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

No annotations are provided, so the description carries the full burden. It doesn't disclose behavioral traits like session persistence, whether this is a long-running/heavy operation (an 'autocoding' workflow with max_turns suggests significant compute), or what state it creates/destroys. It doesn't explain what happens to existing sessions or how this relates to the session_name parameter's lifecycle.

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 single concise sentence grouping the three modes compactly. No wasted words, though the 'g3 coach-player paradigm' parenthetical adds little clarity and could be considered noise. Front-loaded with the primary action.

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 4 parameters, 100% schema coverage, no annotations, and no output schema, the description covers the mode semantics reasonably but leaves questions open: What does successful autocoding return? How does autocode relate to autocode_turn (iteration step) and autocode_session (state container)? Understanding session lifecycle and turn mechanics is important for correct invocation.

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 coverage is 100%, but the description does add value for the key mode parameter by elaborating each mode's purpose ('init: create session state', 'workflow: step-by-step recipe', 'single_shot: one comprehensive prompt'). The requirements parameter's role as 'source of truth' and checklist is reinforced. max_turns and session_name semantics are adequately handled by the schema.

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 does state a verb+resource ('Start autocoding') and explains the three modes. However, it's somewhat vague about what 'autocoding' produces or involves, and it doesn't significantly distinguish itself from sibling tools like autocode_turn or autocode_session. The g3 coach-player paradigm reference is unclear jargon.

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?

The mode descriptions hint at usage ('init: create session state', 'workflow: step-by-step recipe'), but there's no explicit guidance on when to choose this tool versus autocode_turn or autocode_session, nor when to use which mode. The guidance is implied through mode definitions rather than stated.

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