AgentStack (agentstack.tech)

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

Annotations declare destructive/openWorld/readOnly=false, and the description adds genuinely new behavioral context beyond them: the 60000 ms sync lane versus 180000 ms ai_stream widening, the async durable-job path, and enforce_approval pausing financial/destructive/access-control steps for approval. Nothing contradicts the annotations.

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?

It is a single oversized paragraph with no front-loading of the actual operation; the purpose appears after session-order and playbook details. It also carries off-topic meta-instructions ("Cite one number", "do not invent rules.*", "do not quote tools_count") that belong in agent instructions, not a tool definition.

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 complex batch executor with an output schema, the description covers session ordering, sync vs async modes, batching limits, and approval gating, which is close to sufficient. It is weakened by clutter and by incomplete coverage of some nested options, but the essential invocation knowledge is present.

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?

With only 33% schema coverage, the description compensates by constraining steps (ordering, batching cap, one heavy action) and clarifying options fields (async queueing, observed.completed_steps holding ids not action names, workflow_run_id being separate from trace_id). It adds real meaning over the schema, though several options fields remain undocumented.

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 core purpose is stated ("Execute AgentStack operations as steps: id, action, params"), giving a specific verb and resource. However, it is buried mid-paragraph after a long session-ordering preamble, so the reader must assemble the purpose from a dense wall of text. The general resource phrase "AgentStack operations" is broad, though no siblings exist to disambiguate against.

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 gives concrete mode-selection guidance: cheap list/get may batch (max 50 steps), heavy LLM actions are limited to one per sync execute, single heavy steps widen to ai_stream, and large suites use sequential executes or options.async plus polling. The mandatory session order is also spelled out. What is missing is a clean statement of when NOT to call it, but no alternative tool exists.

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