create_multistage_project

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

With no annotations, the description carries the burden, and it does well by disclosing the orchestration mechanism (SequentialOrchestrator) and the nuanced mesh-sharing behavior: first stage imports mesh, later stages either reuse via matching model_part_name or import separately. It doesn't cover side effects like directory overwrites, but the key behavioral trait is well documented.

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 well-structured: it opens with the core purpose, then gives the stage format, then the orchestration context, and finally the mesh-sharing rule. Every sentence adds necessary information without redundancy. It is compact yet covers the essential details for correct usage.

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 tool is complex with 5 parameters and an output schema, but the description explains the most critical input semantics (stage structure and mesh sharing) in sufficient detail. It doesn't describe return values, but the presence of an output schema reduces that burden. Some parameter details are underexplained, but overall it is adequate for a knowledgeable user.

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 input schema has no descriptions (0% coverage), so the description adds critical meaning by defining the 'stages' element structure: {"name": "<stage_id>", "template": "<template>", "overrides": {...}}. It also clarifies the role of model_part_name in mesh sharing. However, it doesn't explain 'create_demo_mesh' or 'stage_checkpoints', leaving some parameters unaddressed.

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 function with a specific verb and resource: 'Scaffold a Kratos multi-stage (orchestrated) case that chains several analyses in sequence.' It also gives concrete examples (continuation run, coupled workflow) and implicitly distinguishes from the sibling 'create_project' by focusing on multi-stage orchestration.

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 provides clear usage context by describing when to use the tool (for chained analyses) and how stages are structured. It also explains the mesh-sharing rule for selecting model_part_name, which guides correct setup. However, it doesn't explicitly state alternatives or exclude single-stage cases, so it falls just short of full guidance.

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