ami_mark_stage

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

With no annotations provided, the description compensates by explaining important behavior: markers are buffered before a survey run exists, they are attached to runs in the same workspace, and an unclosed final stage absorbs subsequent work. This is substantial behavioral disclosure beyond a simple one-line purpose.

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 front-loaded with the tool's purpose and then covers invocation timing and closing behavior without fluff. The buffering sentence is long but still readable and every sentence contributes necessary usage information.

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?

The description covers the full intended lifecycle—opening, buffering, workspace adoption, and closing—and explains the main pitfall of forgetting to close the final stage. Minor gaps around note and run_id remain, but they are not essential for correct selection and basic 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?

The schema covers 4 of 6 parameters, and the description adds meaningful semantics for stage and closes, including lifecycle edge cases. However, note and run_id remain essentially undocumented, and the connection between cwd and buffered markers is only implied.

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 clearly states the tool's purpose—'Declare the workflow stage you are entering'—with concrete examples and ties it to the Agent Effort Profile. It is distinct from sibling tools like ami_survey_begin or ami_record_calls by focusing on stage markers.

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 description gives explicit guidance on when to call the tool ('as you move through the workflow'), when it can be called relative to ami_survey_begin, and how to close the final stage with closes=true. It does not explicitly name alternative tools or say when not to use it, but the workflow context is clear.

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