train_segmentation_model

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

No annotations exist, so the description carries the full disclosure burden. It does disclose inputs, GPU toggle, default output location, and return format ('Dictionary with training results'). However, it omits operational traits important to a training job — expected runtime/resource intensity, whether training blocks or runs asynchronously, and whether input data is modified. Partial but not rich disclosure.

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 core purpose is front-loaded in a single sentence before the Args block. Given 11 parameters and zero schema coverage, the docstring listing is justified — each line is a short, meaningful explanation with no filler. It might be condensed slightly, but the length is proportionate to the documentation burden.

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 description covers all parameters and return format, and the output schema exists so return details need not be repeated. However, for a complex training tool with no annotations, it misses prerequisites such as expected mask/label data format and naming conventions that must match training images, plus initial model availability. Adequate but with gaps an agent would need for a first correct invocation.

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 coverage is 0%, so the description must compensate — and it does. The Args section gives each of the 11 parameters a meaningful one-liner (e.g., 'Base model type (cyto, nuclei, etc.)' offers concrete valid values; 'test_dir: Optional directory with test images' conveys optionality). All parameters are explained beyond their bare names, though entries are brief and lack format details like accepted file extensions.

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?

'Train a custom Cellpose segmentation model' uses a specific verb (train) and specific resource (custom Cellpose model). It clearly differentiates from siblings like `segment_cells_2d`/`3d`/`batch` (inference), `denoise_image`/`deblur_image` (image restoration), and `list_available_models` (model listing). An agent can distinguish this tool without opening schemas.

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?

No explicit guidance states when to use this tool versus alternatives, nor when NOT to use it. Usage is only implied by the verb 'train'. It never mentions that `list_available_models` could be checked first or that `segment_cells_*` handles inference from pre-trained models, so the agent gets no routing cues.

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