Start Snapshots

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that reference_data_dir is not shipped with champollion_pipeline and has no default, but it omits anything about job lifecycle (is this async? does it return a job id?), overwrite/re-run behavior, and expected runtime for a 'render' stage.

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?

Two short sentences, front-loaded with the stage number and outputs before the gotcha about reference_data_dir. Every sentence earns its place, though the backtick/line-break formatting is a little awkward for an agent-facing string.

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?

An output schema exists so return values needn't be described, but for a 12-parameter job-launching tool with no annotations and 0% schema coverage, the description covers only the entry point and one dependency. An agent cannot confidently map most inputs or know whether this is blocking or background work.

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% across 12 parameters, so the description must compensate. It explains only embeddings_dir and reference_data_dir, leaving output_dir (the sole required param), subject, acquisition, the *_only flags, umap_region, and the various *_dir inputs entirely undocumented in both schema and prose.

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 gives a specific verb ('Launch') and a precise resource set framed as 'Stage 6: render sulcal graph meshes, cortical tile masks, and UMAP scatter plots', which clearly separates it from siblings like start_cortical_tiles and start_embeddings. It is specific about what gets produced, though it never explicitly names the alternative stages an agent might confuse it with.

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 'Stage 6' framing implies that earlier stages must run first, and the UMAP precondition ('needs both embeddings_dir and reference_data_dir') is actionable guidance. However, there is no explicit when-to-use/when-not statement, no mention of start_pipeline as an alternative, and no note on whether it can be re-run or resumed.

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