Allocate task

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

With no annotations, the description carries the full behavioral burden. It adds useful behavior about policy-checking, returned task_id usage, and root role constraints (Terra vs Luna). However, it does not disclose idempotency semantics, permission requirements, side effects, or failure behavior, which are significant for a mutation-like allocation tool with zero annotation coverage.

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 tightly written in four short sentences, all carrying useful information. It front-loads the primary action, then gives follow-up behavioral workflow, then adds role/strategy constraints. There is no filler, redundancy, or over-explanation.

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?

This is a high-complexity tool (19 parameters, 10 required, zero schema descriptions, nested objects, no output schema) and the description is far from sufficient on its own. It covers a small fraction of the required calling contract and leaves too many required fields—ID security keys, done criteria, risk, capability pack, budget options—without any guidance. The description's useful hints are not enough to make the tool minimally callable for an agent.

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 only adds semantic value for a few parameters: objective has a 2000-character constraint for fanout Terra, role/model depend on mission.strategy, and the task_id return value is described. Most required parameters such as actorId, idempotencyKey, doneCriteria, risk, capabilityPack, and reasoningEffort are left entirely unexplained by the description, which is critical in a 19-parameter tool.

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 states a specific verb and resource: 'Allocate a policy-checked work package before native spawn_agent.' It also clarifies the tool's role in the lifecycle by saying the returned task_id should be placed into the child's prompt. It does not explicitly differentiate itself from sibling tools like task_claim or task_start, but the 'before native spawn_agent' constraint gives a clear role.

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 when-to-use context: it must be called before native spawn_agent and the returned task_id must be placed into the child's prompt. It also provides situational guidance based on mission.strategy and fanout Terra objective limits. It does not explicitly rule out alternatives or list when-not-to-use conditions.

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