dispatch_agent

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

Annotations only declare readOnly=false, destructive=false and openWorld=false; the description adds that execution is real (no simulated option), that the call blocks and waits for progress, and that a non-null action_required obligates the agent to continue rather than end its turn. The verbatim-first-line rule for meeting_mode_notice is behavior an agent could not derive from structured fields.

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?

Front-loads the action and scope, then routes to alternatives, then gives the follow-up obligations in priority order. It is longer than most descriptions and slightly repetitive ('for example wait_for_task again'), but each clause carries operational weight rather than filler.

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 an output schema present, the description need not explain return values, and it covers the main loop: dispatch, wait, handle action_required, surface meeting_mode_notice. It omits what failure or version-conflict conditions require of the caller and does not point to resume_pending_dispatch or cancel_task, but nothing essential for a correct first call is missing.

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 100%, so role, task_id, project_id, instruction, wait_seconds and context_version are already documented, including the wait semantics and version-conflict rejection. The description only reinforces that the role should come from get_task_status, adding marginal meaning beyond the schema, so baseline 3 applies.

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?

States a specific verb and resource ('Dispatch the configured provider with real execution and wait for progress') and explicitly distinguishes the tool from start_project_request and advance_project by naming them. An agent can tell what this does and what it does not do without opening the schema.

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?

Gives explicit when-to-use ('run a role of an existing task manually, for example a role named by get_task_status') plus two named alternatives with the conditions that select them ('to start a new change use start_project_request', 'to move on after a finished result use advance_project'). It also prescribes post-call behavior for action_required and meeting_mode_notice, leaving nothing to inference.

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