Advance TOCA Workflow

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

Annotations are all false (readOnlyHint: false, openWorldHint: false, idempotentHint: false, destructiveHint: false), so they provide no safety or side-effect context. The description says 'apply a transition', implying a mutation, but it does not explicitly state that this tool changes workflow state, nor does it mention any irreversible effects, authorization requirements, or return characteristics. The only disclosure is that it is 'evidence-bearing', which is unexplained.

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 sentence and is not verbose, but it is severely under-specified. For a tool with eight distinct action variants, a one-sentence generic statement is not appropriately sized or structured. It lacks any enumeration or breakdown, and it does not front-load key information about the different transitions available. This is more under-specification than concise efficiency.

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?

Given the tool's complexity (oneOf schema with 8 actions, many required parameters, no output schema), the description is grossly incomplete. It fails to mention the existence of multiple action types, the requirement for evidence on every transition, the different parameter sets per action, or any side effects. An agent would have no idea how to choose the correct action or what this tool accomplishes beyond a vague 'transition'.

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% (as per input signal), so the baseline is 3. The schema defines all parameters and constraints, but it provides no semantic explanation of what each action does or how parameters like 'evidence' or 'errorCode' are used. The description adds no additional meaning, but since the schema itself is complete in structure, a score of 3 is appropriate per the rubric.

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 'Apply one explicit, evidence-bearing transition through the existing durable workflow engine' is vague. It names a general concept ('transition') but does not specify the concrete actions (e.g., COMPLETE_STEP, FAIL_STEP, RETRY_STEP, etc.) or the resource being acted upon. It does not distinguish this from sibling tools like toca.execute or toca.workflow.create, making it unclear when this tool is the right choice.

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?

There is zero guidance on when to use this tool versus alternatives. No mention of prerequisites, intended scenarios, or exclusions. The description does not even hint at the fact that the tool supports eight distinct transitions, let alone when to use each. This is a complete absence of usage direction.

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