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

With no annotations, the description carries the load, and it does disclose meaningful behavior: notes surface in the viewer, are user-editable, and appear in get_pipeline, list_runs, and the HTML export. It doesn't cover permissions or whether the note is returned, which keeps it from a 5.

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 sentences, no filler; the core action comes first and the visibility/consumers detail follows as supporting context. Every clause contributes information.

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 need not be explained, and the description covers purpose, use cases, and downstream visibility. What's missing is minor but real: no note on permissions or limits, and no mention of what happens when both step and run_id are omitted.

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% and every parameter (step, run_id, text, replace) is documented in-schema, so the schema already does the heavy lifting. The description's 'to a step or a run' only echoes the schema's own 'give step OR run_id' guidance, adding no new syntax or format details.

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?

Uses a specific verb (add) plus resource (note) and states the two attachment targets (step or run), so the agent can distinguish it from siblings such as tag_run or log_run with no schema inspection.

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 examples 'why a run failed, what a step assumes, or a conclusion from a comparison' give concrete situations that call for this tool, which is stronger than generic context. It stops short of naming alternatives or exclusions, so it stays at 4 rather than 5.

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

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 an existing name is updated rather than rejected, but is silent on what an update replaces (are stale inputs/outputs/params discarded or merged?) and on whether the step is persisted immediately.

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?

A single front-loaded sentence with zero filler; the upsert caveat is placed where it will be read.

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?

With a rich six-parameter schema and an output schema present, the description need only cover intent and side effects. Intent and upsert semantics are covered; the only real gap is the precise overwrite/merge semantics of the update path.

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% and every parameter carries a concrete example, so the schema does the heavy lifting. The description adds no extra meaning about parameter interaction, such as whether outputs must match a downstream step's inputs.

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?

States a specific verb and resource ('Register a pipeline step') plus the domain framing ('a node on the map'). It also discloses the upsert behavior, which distinguishes it from a pure create. It doesn't explicitly contrast with sibling connect_steps, but the resource distinction is inferable.

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 no statement of when to call this versus connect_steps, get_pipeline, or init_project, and no prerequisites (e.g., must a project exist first?). The only guidance is implicit in the upsert clause.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It does disclose that only succeeded runs are considered and that selection is metric-based, but it omits tie-breaking behavior, permission requirements, and whether 'succeeded' has any special semantics.

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 front-loaded sentence with no wasted words. It is appropriately brief for a tool whose schema and output schema carry most of the structural detail, though it could provide slightly more framing around the key qualifier 'best'.

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 simple, with full schema coverage and an output schema, so the description does not need to explain parameters or return values. However, with no annotations, it remains incomplete on behavioral details such as tie handling and permission expectations.

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%, so metric, mode, and step are already well documented. The description mentions the metric concept but adds no syntax or usage detail beyond what the schema provides, making the baseline 3 appropriate.

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: find the best succeeded run by a metric. It is understandable without opening the schema, but it does not differentiate itself from list_runs or explain what 'best' means, so it falls short of full sibling-level clarity.

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 no explicit guidance on when to use this tool versus list_runs or other siblings. The phrase 'Find the best succeeded run' implies the use case, but no alternatives, prerequisites, or exclusions are mentioned.

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

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

With no annotations, the description carries the full behavioral burden, and it does add real value by disclosing the termination mechanism (SIGTERM, escalating to SIGKILL after 5 s), signalling a forced, likely non-graceful termination. It omits other important traits: whether cancellation is reversible, what happens to partial results or checkpoints, and whether cancelling a sweep cascades to its child runs.

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?

A single compact sentence with the core action and the key mechanic (SIGTERM/SIGKILL timing) front-loaded, and no filler. The parenthetical is dense but every clause earns its place.

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 need not be explained, which lowers the bar. Still, for a destructive, annotation-free operation on runs and sweeps, the description should say what happens to in-flight work and whether sweep cancellation propagates to child runs; those gaps matter for 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 description coverage is 100% and the run_id description already states it accepts a sweep id as well as a run id, so the description adds little parameter-level detail. Its mention of 'a whole sweep' echoes rather than extends the schema, which is consistent with the baseline 3 for fully-covered single-parameter tools.

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?

States a specific verb (stop) and resource (run or sweep) with an added scope qualifier ('started from this session') that separates it from other run-level tools. It does not explicitly name which siblings it supersedes or differs from, so identification relies on the reader inferring against run_step/run_sweep/start_sweep.

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 phrase 'started from this session' implies a precondition for use, and 'or a whole sweep' hints at the sweep-cancellation case. However, there is no explicit when-to-use vs when-not-to-use guidance and no alternative tool is named for cases where the run was not started in this session.

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

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

With no annotations provided, the description carries the full disclosure burden, and it does surface meaningful behavior: the four categories of comparison output and the non-obvious constraint that the script diff only covers the first two runs. It stops short of stating that this is a read-only/non-mutating operation or any limits on run count or cost.

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?

A single sentence, front-loaded with the verb, then a tight enumeration of outputs. No filler, no restatement of the title, and every clause carries information.

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 and parameters are fully documented, so the description needn't explain return shapes; what it adds is the right shape of summary for a read-only comparison tool. Minor gaps remain around minimum run count enforcement and error behavior with a single run id.

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%, so run_ids and code_diff are already fully documented, including the baseline rule and the first-two-runs diff scope. The description restates rather than extends that semantics, which is the defined baseline of 3.

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?

States a specific verb+resource ("Compare runs") and enumerates exactly what the comparison yields: differing params, metrics, data versions, and a script diff. It is clearly distinct from list_runs, best_run, and run_log. It loses a point only because it never names a sibling to contrast against explicitly.

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?

Usage is implied rather than stated: "params that differ (baseline -> each run)" signals that you supply multiple run ids with the first as baseline, which tells an agent when the tool fits. There is no explicit when-to-use, when-not-to-use, or alternative such as best_run for picking a winner instead of comparing.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses two key constraints (existence prerequisite and cycle rejection), but omits what happens on failure, whether the edge is idempotent, or whether it mutates persisted graph state.

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 compact sentences with the operation first and the constraints immediately after; every clause carries information.

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 need no explanation, and the essential preconditions are stated. Only the failure/error behavior of the cycle or missing-step cases is left unstated.

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 100%, so source/target direction and the optional label are already documented in the schema. The description's ordering implicitly reinforces direction but adds no syntax or format detail beyond the structured fields.

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?

States a concrete verb (draw a directed edge) with explicit source -> target roles, which cleanly separates it from node-creating siblings like add_step. It doesn't name a sibling directly, but the semantics are unambiguous.

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?

Preconditions ("both steps must exist; cycles are rejected") imply when the call will succeed, but there is no explicit guidance on when to use this vs. alternatives like add_step or log_run, and no mention of what to do on rejection.

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

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

With no annotations provided, the description carries the load and does it: it declares the read-only contract ('Reads files only; runs nothing') and explains the comparison logic against the latest run, which is the key behavioral trait. It omits cost/latency considerations for hashing large file sets.

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 output (hashes, latest-run comparison, staleness) is front-loaded, and the trailing 'Reads files only; runs nothing' earns its place as a safety signal. The parenthetical is slightly dense but no sentence is wasted.

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 need not be spelled out, and the description still covers read-only behavior, scope, and the staleness interpretation. Nothing an agent needs in order to call it correctly is missing.

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 single `step` parameter is fully documented in the schema ('Only this step (default: all)'), and the description's 'every step's input and output files' corroborates the all-steps default. That is baseline-level value, no additional semantics about step identifiers or scoping.

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?

States the concrete resource precisely: SHA-256 hashes of each step's input/output files, the hashes the latest run used, and which inputs changed since. That is a specific, unambiguous verb+resource pair an agent can distinguish from siblings like list_runs or run_log, though no sibling is named explicitly.

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?

Implies the decision it supports -- 'which inputs changed since (so the step is stale and should be re-run)' -- giving the agent a clear trigger for calling it before re-running or sweeping. It also closes off misuse with 'reads files only; runs nothing', though it never names run_step or list_runs as the alternative actions.

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

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

With no annotations, the description carries the full burden and does well: it discloses the output is self-contained, read-only, offline, requires no server, and returns file path and size. It flags that scripts are embedded by default and that the user must be warned before sharing – a genuine safety trait. It omits what happens to an existing file at `path` (overwrite/failure), which keeps it from a 5.

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 action and the contents list are front-loaded in the first sentence, and the sharing caveat is separated so it reads as a distinct instruction. The parenthetical content list and the stray line breaks add slight clutter but no wasted sentences.

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 need not be spelled out, yet the description still notes path and size. All parameters are documented, the behavioral scope is covered, and the share-safety caveat is included – nothing an agent needs to call this correctly is missing.

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%, so baseline is 3, but the description adds real meaning beyond the schema: it explains the consequence of `include_scripts=false` (scripts omitted, and the sharing warning no longer applies). It does not add anything about `path` semantics, which the schema already covers with its default.

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?

States a specific verb and artifact: 'Write a single self-contained HTML file of the map', and enumerates its contents (steps, code, runs, experiment tree, compare). It does not distinguish itself from the sibling open_map, which an agent could easily confuse it with, so it falls short of a 5.

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?

Gives clear situational context: the file opens offline with no server so the user can email it, post it in Slack, or host it on GitHub Pages/gist. This tells the agent when the tool is appropriate, but there is no explicit exclusion or pointer to open_map as the interactive alternative.

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

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

No annotations are provided, so the description must carry the full behavioral burden for this mutation operation. It states that the sweep is marked finished and that a summary is returned, but it does not disclose important details like idempotency, required permissions, effects on in-flight trials, or error conditions.

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 focused sentence with no wasted words. It front-loads the action and then mentions the return summary, which is appropriately sized for this simple tool.

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 has an output schema, so the description does not need to explain return formatting in detail. However, with no annotations and only implicit usage guidance, the definition is somewhat thin for a mutation operation whose status parameter has behavioral implications.

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%, so the parameters are already well documented by the schema. The description adds no parameter-level detail beyond what the schema provides, which is acceptable at the baseline for high coverage.

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 names a specific verb and resource: 'Mark a sweep finished'. It also clarifies that the tool returns a summary with trial counts and the best trial. It does not explicitly compare itself to siblings like start_sweep or best_run, but its purpose is unambiguous.

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 usage is implied by 'finished', meaning this should be called when a sweep is complete. However, there is no explicit guidance on when to choose finish_sweep versus alternatives such as cancel_run, or how to pick the status value.

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

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

No annotations exist, so the description carries the burden; it does establish that this is a retrieval ("Return") with no arguments and tells the agent the data includes run status, which signals freshness comes along with the map. It says nothing about cost, size, permissions, or whether the call has side effects, which matters for a zero-param call whose name does not itself imply read-only semantics.

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?

One sentence, front-loaded with the object returned, then the enumerated contents. No filler and nothing buried.

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?

With no parameters and an output schema present, the description needn't document return values, and the shape of the payload is briefly characterized. But with zero annotations and several plausible sibling tools that also surface map data, the definition leaves the agent without routing criteria or any note on cost/freshness.

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 tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies no scoping inputs are needed to fetch the whole map.

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 uses a clear verb ("Return") and specific resource ("the whole map"), then enumerates the payload: nodes with params, script and latest run status, edges, and a topological order. An agent knows exactly what it gets. It falls short of a 5 because it never distinguishes itself from siblings like open_map or export_map, which plausibly return the same map.

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 no guidance on when to call this versus open_map, export_map, or list_runs. The word "whole" faintly implies a full fetch rather than a partial one, but no explicit condition or alternative is named.

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

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

The description excels here by contrasting two behavioral states: the default state where models are read 'statically... nothing is imported or run' versus the `introspect` state, which explicitly states that loading files 'can execute code.' This is critical behavioral context.

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 dense and highly technical, serving as a comprehensive single block of text. While efficient, its structure is very complex, typical of GNN tooling.

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 that an output schema exists, the description does not need to explain return values. It comprehensively defines the inputs, the scope of the summary, and the behavioral risks, making it a complete definition.

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?

Even with 100% schema coverage, the description adds massive value, especially for the `introspect` parameter, by detailing the dangerous subprocess actions (torch.load, unpickling) that occur when that flag is set.

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 precisely defines the scope of the tool as a 'GNN view of a step,' detailing exactly what information is extracted (model architecture, dataset classes, cached stats). This highly specific definition clearly separates it from other general step management tools.

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?

While it doesn't start with a high-level 'when to use' statement, it defines its utility by listing the specific GNN data it provides. The strong warning within the `introspect` parameter provides crucial usage guidance regarding potential execution risks.

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

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

With no annotations at all, the description carries the full behavioral burden, and it does disclose the key risk trait: idempotency ('safe to call again'). It leaves open what happens to pre-existing files (overwrite vs preserve), whether permissions are required, and whether the call is slow — gaps that matter for an initialization/mutation 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?

Two short sentences, zero filler, with the concrete side effects front-loaded before the idempotency note. Every clause earns its place.

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?

Output schema exists and annotations are absent but the tool is simple (one optional param), so the description covers nearly everything needed: what is created, where, and that re-invocation is safe. Only the overwrite/permission behavior on existing stores is unaddressed.

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 100% and the single optional 'name' parameter is fully documented in the schema ('defaults to the folder name'). The description adds no parameter-level detail, so the schema baseline of 3 applies.

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?

States a specific verb (Create) and resource (.mltree/ store) and enumerates the artifacts produced (pipeline.yaml, mltree.db, runs/), so the agent knows exactly what will exist afterward. It does not distinguish itself from siblings such as scan_project, but no sibling plausibly competes for the same action.

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?

Usage is only implied: creating the store is obviously a prerequisite step, but the description never says when to call it, when not to, or how it relates to scan_project. 'Safe to call again' informs repeated invocation but is not selection guidance.

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

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 discloses that results are ordered newest first, but does not state that the operation is read-only, whether it has side effects, or how pagination behaves beyond the schema's limit parameter.

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 front-loaded sentence with zero waste. Every word contributes directly to the operation and its ordering behavior.

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 schema fully documents all parameters and an output schema exists, so the description needn't explain return values or parameter details. However, with no annotations and no usage guidance, the description leaves important behavioral and selection context unstated.

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%, so all four parameters are already documented in the schema. The description adds no parameter-specific meaning beyond the ordering note, making the baseline score of 3 appropriate.

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 clear verb and resource ('List runs') plus an ordering behavior ('newest first'), so an agent can understand the core operation. It does not explicitly differentiate itself from sibling tools such as best_run or log_run, though those appear to be distinct operations.

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 no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The agent must infer usage entirely from the tool name and schema.

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

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 context that SHA-256 versions of input/output files are recorded so later runs can detect data changes, but it does not state that this is a write/mutation operation, nor does it cover permissions, duplicate handling, or error behavior.

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 sentences, front-loaded with the core action and followed by one sentence of useful behavioral context about data versioning. No filler and no repetition.

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 need not be explained, and full schema coverage documents the parameters. But with 11 parameters and no annotations, the description should still clarify write semantics and distinguish this tool from run_step and run_log; those gaps keep it from being complete.

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%, so all 11 parameters are already documented in the schema. The description restates some of the same fields (params, metrics, artifacts, parent run) without adding syntax, format, or edge-case semantics beyond what the schema provides, so the baseline of 3 applies.

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: 'Record one execution of a step', and enumerates what is captured (params, metrics, artifacts, parent run). However, it gives no differentiation from similarly named siblings such as run_step, run_log, and list_runs, so an agent cannot tell from the description alone which tool to pick.

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 no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives like run_step or run_log. Usage is only weakly implied by 'Record one execution of a step', leaving the agent to infer routing from the name alone.

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

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

With no annotations, the description carries the burden, and it does disclose the key side effect: the viewer may be started in the background. It says nothing about process lifetime, what happens if the port is occupied, or the security implication of enabling Run buttons, so meaningful gaps remain.

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, zero filler, with the action and its conditional side effect front-loaded ahead of the delivery instruction.

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 the return value (a URL) needn't be explained, and the description covers the conditional start behavior. Minor gaps remain around failure modes and whether the started viewer persists, but nothing essential to invoking it correctly is missing.

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% – port defaults, the start flag, and the allow_run condition are all documented in the schema itself. The description adds no parameter meaning beyond that, so baseline 3 applies.

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?

States a concrete verb and resource: return the URL of the mltree map viewer, and start it if needed. It is clearly distinguishable from siblings like export_map or get_pipeline, though it never names an alternative to contrast 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?

'Give the URL to the user' is a delivery instruction, not a selection rule. There is no statement of when to prefer this over export_map or get_pipeline, and no exclusions; usage context is only implied.

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

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

No annotations are provided, so the description carries the behavioral burden. It does disclose that output is live during execution and includes status alongside log tail, but it omits details like permissions, truncation behavior, or handling of finished/failed runs. Given the presence of an output schema, the return format gap is mitigated, making a 3 appropriate.

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?

A single, efficient sentence that front-loads the action and resource. The parenthetical adds a useful nuance without bloat, though there is minimal structure beyond that one sentence.

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?

For a simple two-parameter read tool with a fully described schema and an output schema, the description covers the essentials: what it returns and when it is live. Missing details (e.g., behavior on completed runs) are minor given the structured coverage.

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%, so both parameters (run_id and tail) are already documented in the schema. The description adds no extra meaning about the tail parameter's behavior or run_id format, so the baseline 3 applies.

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 ('Return') and resource ('status and the last lines of a run's log'), making the tool's function immediately clear. It does not explicitly differentiate itself from siblings like log_run or list_runs, which keeps it just short of a 5.

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 parenthetical '(live while it runs)' hints that the tool can be polled during an active run, which is useful implied guidance. However, there is no explicit when-to-use vs. when-not-to-use guidance or reference to alternatives such as log_run, leaving usage to inference.

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

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

With no annotations, the description carries the full load and does well: it discloses that arbitrary script code is executed as a subprocess, that params are injected three different ways plus $MLTREE_PARAMS, and exactly what gets persisted (params, script snapshot, command, exit status, duration, log path, metrics). It does not state whether a run record is still written when the script fails or whether execution mutates project state beyond recording, which keeps it from a 5.

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 action is front-loaded in sentence one, and the following clauses are dense but information-bearing rather than filler. The long parenthetical enumerating param-passing styles is slightly cramped reading but not wasteful.

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?

For a 6-param mutating execution tool with no annotations, the description covers the mechanism, the side effects recorded, the log and metrics conventions, and even summarizes the return value (the run plus the tail of its log) despite an output schema existing. An agent has enough to call it correctly without opening anything else.

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 100%, so the baseline is 3, but the description genuinely adds semantics the schema lacks: it explains how `params` is transformed per script framework (argparse/click flags, positional sys.argv, hydra key=value, always $MLTREE_PARAMS JSON) and how metrics are detected from stdout or $MLTREE_METRICS_FILE. The remaining params (wait, timeout_s, extra_args, parent_run_id) are already well documented in the schema.

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 opening sentence gives a specific verb and resource: 'Execute a step's script as a subprocess and record it as a run automatically.' An agent knows exactly what happens (subprocess execution plus automatic run recording). It does not, however, explicitly contrast itself with nearby siblings like run_sweep or cancel_run, so it falls short of a 5.

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?

Usage is implied by the mechanics described (params get passed as CLI flags, which presupposes a script that accepts arguments), but the description never states when to choose run_step over run_sweep, or what preconditions exist (step must exist, project must be initialized). No exclusions or alternatives are named.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It usefully states that execution creates one sweep run plus child runs and runs combinations one after another, but it does not disclose permissions, failure behavior, blocking semantics, or side effects.

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 front-loaded sentence with no wasted words. It communicates the core action and execution model efficiently.

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 has nine parameters, a nested grid object, and an output schema, so the description is only moderately complete. It explains the run structure but omits operational details such as blocking behavior, failure handling, and how the sweep relates to start_sweep/finish_sweep.

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%, so the schema already documents all nine parameters, including grid, mode, step, wait, metric, and max_runs. The description adds the notion that each combination produces a child run, but it otherwise does not add meaning beyond the schema.

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 ('Run a grid search') and explains the resulting run structure: one sweep run plus one child run per combination, executed sequentially. This is clear, but it does not distinguish the tool from sibling tools such as start_sweep, run_step, or finish_sweep.

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 contains no explicit guidance about when to use this tool instead of start_sweep, run_step, or other sibling tools. The name and short description imply a grid-search use case, but there are no stated exclusions, prerequisites, or alternative-selection rules.

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

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

With no annotations, the description carries the full burden and does so: it discloses the safety profile (AST only, user code never executed), mutation semantics (re-scans update scanner-owned fields, add steps, never delete), edit preservation (keeps changes made with add_step), and side effects (imports results as runs tagged 'imported').

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?

Front-loaded with the core purpose and no filler; each subsequent sentence covers detection scope, idempotency, and next steps. The middle sentence is a dense run-on list that could be split for faster scanning.

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?

All six parameters are documented in the schema, an output schema exists so return details needn't be restated, and the description still covers safety, idempotency, and correction workflow. Nothing an agent needs to invoke it correctly is missing.

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 100%, so parameters are already documented; the description nevertheless adds meaning the schema lacks, notably what import_results produces (runs tagged 'imported'). It does not explain include/exclude interaction or default traversal cost, keeping it below schema-plus-extra depth.

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?

Opens with a specific verb+resource ('Build the map of an EXISTING project') and immediately scopes the mechanism ('by static analysis (ast only; user code is never executed)'). The capitalized EXISTING implicitly separates it from init_project, and the enumerated detections (data reads/writes, CLI params, imports, step kinds) make the output concrete.

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?

Clearly positions the tool in the workflow: run it, then 'fix it with connect_steps / add_step', and explains the idempotent re-scan case. It never explicitly says when NOT to use it (e.g., a brand-new project should use init_project), so exclusions stop short of a 5.

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: it creates a grouping that persists, its id must be threaded into subsequent log_run calls, and the map renders the group as a collapsible fan with the best trial highlighted. It does not say whether creation mutates/commits project state or what happens on a duplicate/invalid step, so it stops short of full 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?

Three tight sentences: what it creates, how to consume its output, and the sibling alternative. The parenthetical 'an HPO study / grid search' is a worthwhile disambiguation rather than filler.

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 need not be explained, and the description covers the creation semantics, the id hand-off, and the routing decision. It leaves open what happens if metric is omitted (no best-trial ranking) and whether the sweep must be closed with finish_sweep, both of which an agent would benefit from knowing.

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% and each parameter carries its own description (mode, name, step, metric, search_space, parent_run_id), so the schema does the parameter work. The description adds no syntax or semantics for any of the six parameters beyond referencing the returned sweep_id, so baseline 3 applies.

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?

States a specific verb and resource ('Create a sweep') and immediately glosses it as 'an HPO study / grid search that groups trial runs', which makes the concept unambiguous. It also distinguishes the tool from its closest sibling by describing what log_run and run_sweep do relative to it.

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?

Gives explicit usage protocol ('Pass its sweep_id to log_run for each trial') and an explicit alternative with the condition that selects it ('Use run_sweep instead to have mltree launch a grid itself'). An agent knows both the follow-up step and when to pick the other tool.

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

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

No annotations are provided, so the description carries the burden. It discloses the mutation intent and a real side effect (tags drive tree highlighting), which is genuine context, but it omits idempotency, behavior on duplicate/absent tags, and permission requirements.

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 core action and followed by the observable effect. Nothing wasted.

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 need not be explained. Still, for a mutation with zero annotation coverage, the description leaves open whether add/remove are exclusive, how existing tags are preserved, and what errors to expect.

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 100%, so each parameter is already documented in the schema. The description adds only naming-convention examples for tag values, which is a modest increment over what the schema states.

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?

Specific verb pair ('Add or remove') plus resource ('tags on a run'), with concrete tag examples. It is implicitly distinct from siblings like add_note or log_run, though it never names an alternative to bound the scope.

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 example tags ('baseline', 'best', 'final') imply the intended use case, and the second sentence hints at why tagging matters (tree highlighting). There is no explicit when-to-use, no exclusion of alternatives, and no statement about whether add and remove can be combined in one call.

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