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

With no annotations, the description carries the full burden of disclosure. It usefully reveals non-obvious staged behavior — the first call is a discovery call returning a rubric and candidate schema rather than scores, and scores only appear when candidates are supplied. It says nothing about side effects, whether it is read-only, cost/latency, or permissions.

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 terse sentences, front-loaded with the purpose, then the I/O contract. The pseudo-signature notation is compact and dense, though the bracket/pipe shorthand demands careful reading and borders on cryptic for an agent unfamiliar with this namespace.

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 spelled out, and the description rightly focuses on the call protocol instead. Still, for a tool with a nested, untyped payload, key details are missing: permissible `kind` values, trace path semantics, and what a candidate must contain to be scored.

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% and the schema is a single untyped `payload` object with additionalProperties: true, so the description must compensate entirely. It does sketch the field structure ({workflow:{kind, text|path}, [traces:{path}], [candidates]}) and marks optional fields, but never enumerates valid `kind` values, explains text-vs-path selection, or defines the `candidates` object shape.

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: 'Find decision points in a workflow.' That is clearly distinct in kind from the sibling family (register/decide/record/train), even though no sibling is named explicitly. The second sentence describes input shape and phased returns, which reinforces the purpose.

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 implies a two-step usage pattern ('First call returns rubric + candidate_schema + hints; with candidates, returns score and verdict'), which tells the agent something about the call sequence. However, it never says when to use dm_analyze versus siblings like do_analyze, dm_plan_run, or dm_decide, and gives no prerequisites or exclusions.

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 must carry the whole behavioral burden. It does disclose that the operation is read-only and describes the return semantics including the 'on|off|blocked(reason)' status domain and the gate each point waits for. It says nothing about authentication, rate limits, or whether the hashes can change concurrently, so the disclosure is partial rather than complete.

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 zero filler. The read-only qualifier is front-loaded and the return contents follow immediately, so the reader gets the important fact first.

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 output schema means return values need not be spelled out, and the description covers them anyway. However, for a call with a required, completely undocumented 'payload' object, the definition does not give an agent enough to invoke it correctly, which is a material gap for an otherwise simple status tool.

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?

There is one required parameter, 'payload', declared as a free-form object with additionalProperties true and 0% schema description coverage. The description never mentions what belongs in that payload, so the agent has no way to know whether it can pass an empty object or must supply fields. The schema and description together leave the parameter undefined.

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 resource ('autopilot state') and enumerates what the response contains: approved and current hashes, eligible points, per-point status, and the gate being awaited. That is far beyond a tautology. It doesn't explicitly contrast with the parallel do_autopilot_status sibling, which keeps it from 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 only usage signal is the parenthetical '(read-only)' plus the word 'status', which implies an inspection call. There is no statement of when to call this versus do_autopilot_status or the plan-run siblings, and no preconditions are given.

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 behavioral burden. It discloses mode semantics and the expected follow-up action (do_record in teacher mode), but it does not state whether the call mutates state, what permissions are required, or any rate limits.

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 compact and front-loaded, moving from purpose to input, return, and mode behavior without filler. The bracket notation is efficient but slightly cryptic, which keeps it from being maximally clear.

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?

Because an output schema exists, the description need not fully explain return values, and it does provide the key mode semantics. However, the input schema is nearly empty and the description does not fully explain the nested payload fields or the safety profile, so an agent still lacks important context 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?

The schema describes only an opaque payload object with 0% property-level coverage, so the description must compensate. It usefully enumerates expected fields as point_id*, context*, and optional teacher_cost, but it does not explain their meaning, types, or formats, leaving significant semantic gaps.

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?

"Ask for a decision" states a verb and resource, but the purpose remains abstract: it does not say what kind of decision, in what domain, or how it differs from sibling tools such as do_decide. The mode and return details add some clarity, but the core purpose is still vague.

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 gives mode-specific handling: in teacher mode decide yourself and then do_record, while in auto/rule mode use the returned choice. It does not explain when to call dm_decide instead of alternatives like do_decide, nor does it state prerequisites or exclusions.

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 it does disclose two behavioral facts: the output payload is JSONL and private points require an explicit confirm flag (a confirmation/safety gate). It does not say whether the operation is read-only on the store, whether it errors or silently skips private points without confirm, or what it does when the target path already exists.

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 terse sentences, front-loaded with the purpose and followed by the payload contract; nothing is wasted. The pseudo-signature notation "{point_id*, path*, [confirm]}" is compact but slightly cryptic compared to plain prose.

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 key payload fields are covered. For an export tool writing to a filesystem path, though, the description omits overwrite behavior, error cases, and what "labelled" filters, leaving meaningful gaps.

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% and the schema hides everything behind a single opaque `payload` object, so the description does real work by enumerating point_id* and path* as required and confirm as optional. It falls short of 5 because it never explains what a point_id refers to or whether path is a file or directory target.

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?

"Export labelled rows as JSONL" names a specific verb (export), resource (labelled rows), and output format (JSONL), which is far better than a tautology. It does not differentiate against the near-identical sibling do_export, so an agent cannot tell from the description alone which of the two export tools 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?

The conditional "Private points need confirm:true" gives a real prerequisite rule for one class of input, which is useful usage guidance. However, there is no statement of when to prefer dm_export over do_export or the other dm_* siblings, and no note on what happens if confirm is omitted for a private point.

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 supplied, the description carries the full burden and does disclose meaningful behavior: the operation is two-call, Call 1 yields transcript_id, extraction_id, points and record_schema, and Call 2 returns accepted plus rejected with one code per check plus jev_disagreements. That tells the agent this is a validating, feedback-driven mutation. It omits side-effect scope, idempotency, and any permission or contributor-confirmation semantics behind the 'contributor_off_confirmed' flag.

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 purpose, then split cleanly into Call 1 and Call 2 blocks with the payload shape inline; nearly every token carries information. The telegraphic brace-and-pipe notation is dense enough that it takes careful parsing, which costs some readability.

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 a nested free-form payload and an output schema that already documents returns, the description supplies the essential missing piece: the two-call contract and the payload keys. Domain terms like 'points', 'record_schema', and 'jev_disagreements' are left undefined, and the audit-pass trigger is stated but not motivated.

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% and the entire schema is one opaque 'payload' object with additionalProperties true, so the description is the only source of parameter meaning. It does enumerate the acceptable keys for both call shapes (transcript|path|transcript_id, contributor_off_confirmed, extractor_local, pass: 2, extraction_id, extractor, records, new_points) and marks the required ones with asterisks. It stops short of explaining types or the meaning of flags like extractor_local and contributor_off_confirmed.

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: "Extract decision labels from a one-turn transcript (two calls)". The two-phase nature is made explicit, so the agent knows this is not a single-shot operation. It does not, however, distinguish itself from sibling extractors such as do_extract or dm_analyze, which an agent would need to tell apart.

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 spells out the invocation sequence in detail (Call 1 with a transcript-or-path-or-id payload, or pass: 2 for the audit pass; Call 2 with extraction_id/extractor/records plus optional new_points), which is real procedural guidance. What it never says is when to prefer this tool over do_extract or the dm_* analyze/decide siblings, nor when the optional audit pass is required versus optional.

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 supplied, so the description carries the full burden. It signals a write ("attach"), but never says whether an existing outcome is overwritten, whether the call is idempotent, what permissions or decision state are required, or what happens if both ok and correct_choice are omitted.

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?

It is short and front-loaded, with the constraint sentence placed after the field list where it belongs. The "Input: {decision_id*, [ok], ...}" bracket notation is cryptic but compact; the main waste is the vague opening 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?

An output schema exists so return values need not be explained, but for an unannotated mutation with a fully opaque payload the description is still thin: the plan_id reference is unexplained and inconsistent with the schema, and the overwrite/error behavior of the write is not covered.

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% and the only parameter is an opaque `payload` object with additionalProperties: true, so the description's field list (decision_id required, optional ok/correct_choice/note) is genuinely valuable. However it also introduces a `plan_id` that appears nowhere in the schema, leaving the actual accepted payload shape ambiguous.

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?

"Attach the real outcome" names a mutation on an outcome record, and the field list (decision_id, ok, correct_choice, note) hints at a decision-outcome resource. But the phrasing is jargon-heavy and it never distinguishes itself from near-identical siblings such as do_outcome, dm_record, or do_record.

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 only usage rule is "Either ok or correct_choice may be given," which is a constraint rather than a when-to-use guideline. There is no statement of when this tool is correct versus do_outcome/dm_record, and no prerequisites or sequencing 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 burden. It hints that a workflow check may be triggered ('when deterministic') but never explains permissions, side effects, idempotency, or what 'deterministic' means here — a significant gap for a write tool with no annotations.

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?

Terse and front-loaded, but the pseudo-signature 'Input: {plan_id*, [transcript], ...}' is cramped and its bracket/asterisk notation is never explained. It's efficient but cryptic rather than clear.

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. Still, for a mutation tool with no annotations, a nested free-form payload, and 0% schema coverage, the description should explain the payload's shape and the 'workflow check' side effect more fully.

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% and the single 'payload' parameter is an untyped object with additionalProperties true. The description lists internal payload keys (plan_id*, transcript, final_output, cost, conflict, trial_id, pair_id, arm) that appear nowhere in the schema, adding some meaning, but it doesn't specify types or formats for those keys.

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 ('Record a planned run's result'), which distinguishes writing a result from siblings like dm_plan_run. However, it never clarifies what a 'planned run' or a 'plan result' is, and the sibling dm_plan_run is not contrasted explicitly, leaving the boundary vague.

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 statement of when this should be used versus dm_plan_run, dm_record, or do_plan_result. The only usage hint is the cryptic 'Runs the workflow check when deterministic', which doesn't tell an agent when to call this 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 supplied, so the description carries the full burden, and it does disclose the decision vocabulary (inject/downgrade/none) and the dual outcome shape (prompt_addendum vs would_have), which hints at a dry-run/trial behavior. It says nothing about side effects, whether state is persisted, auth requirements, or how the recommendation is applied, which are the gaps that matter for a planning tool.

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, purpose front-loaded, no filler. The brace notation is dense and reads like a schema fragment, but every token carries information and nothing 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 the return sentence is bonus rather than mandatory, and the payload key inventory partially compensates for 0% schema coverage. Against a 10-field nested payload and 25 same-family siblings, however, the absence of selection guidance and field meaning leaves real ambiguity.

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% and the single parameter is an untyped free-form object, so the description is the only documentation of the payload. It enumerates ten inner keys and marks three as required (workflow*, input*, context*) versus optional via brackets, which is substantial added meaning. It stops short of explaining what each field accepts or what values pilot_mode/run_model take.

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?

"Plan one-turn work" names a verb and a loose scope, and the return sentence (recommendation of inject/downgrade/none plus prompt_addendum or would_have) makes the intent slightly more concrete. But it never distinguishes itself from near-identical siblings such as dm_plan_result, do_plan_run, or do_plan_result, so an agent cannot tell which planner to pick from the description alone.

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 when-to-use guidance at all: no conditions, no exclusions, no mention of the obviously overlapping siblings. An agent must infer usage entirely from the name and the payload key list.

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 disclose real gating behavior (credentials, budget, remote_ok, trial-passed requirement for downgrade) and the need for user confirmation before serve. It omits side effects, reversibility/rollback, and what happens when checks fail, which matters for a state-changing operation.

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 bracketed signature puts the required fields and phase enum up front, and every sentence adds a distinct rule. It is dense and telegraphic, however, relying on abbreviated spec citations that cost more decoding effort than they save.

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?

Return values are covered by the output schema, and the description covers the promotion gates well. For a tool this intricate it still leaves out failure behavior, ordering of the §6.4 checks, and the semantics of the single nested `payload` wrapper, all of which an agent needs to invoke it correctly.

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% and the actual schema is an opaque untyped `payload` object, so the description must supply all parameter meaning. It does enumerate fields with required markers (point_id*, phase*) and an inline enum (collect|shadow|serve|paused), but it never states that these are keys inside `payload`, and it mixes mode fields (plan_phase, workflow, downgrade) into the same flat notation.

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?

It states a verb and resource ("Move a point") and names the three modes (phase move, plan_phase move, workflow downgrade). However, the vocabulary is heavy domain jargon (point, phase, probe, tiered, remote_ok) with no glossary, and the meaning is partially deferred to opaque section references (§6.4, §15.6, §15.8), so an agent cannot fully tell what it does without outside docs.

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 gives concrete preconditions per target phase: shadow requires a trained probe or hosted key + budget + remote_ok, and serve requires all §6.4 checks plus confirm:true with an explicit "ask the user first" instruction. It also routes between modes via plan_phase and workflow+downgrade, though it never explicitly says when NOT to use it versus sibling tools like dm_train or do_promote.

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 mentions the choice constraint but does not disclose side effects, idempotency, permissions, or what happens when the choice is invalid or the record already exists.

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 short and front-loads the purpose before listing inputs. The dense input notation is efficient, though it sacrifices some readability.

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 output schema exists, so return values need not be explained. The description covers the essential input fields and a validation rule, but for a mutation tool with no annotations and a generic payload schema, it omits important behavioral context such as side effects and failure handling.

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 schema exposes only a generic payload object with 0% description coverage, so the description adds meaningful detail by naming decision_id, choice, and teacher_cost, marking two as required, and constraining choice to allowed_options. However, it still does not explain teacher_cost, decision_id, or the payload wrapper, leaving partial compensation for the schema gap.

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 says 'Record the teacher's choice,' which gives a specific verb and resource rather than restating the tool name. It does not differentiate this tool from close siblings such as dm_decide or do_record, 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?

There is no explicit guidance on when to use this tool instead of alternatives, nor any stated prerequisites. The phrase 'Record the teacher's choice' implies it follows a decision, but the agent must infer that context.

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 supplied, so the description carries the full burden. It discloses the return behavior (stored point plus a call snippet to paste into the skill), which is useful, but says nothing about overwrite semantics when point_id already exists, permission requirements, validation failures, or whether updating is destructive.

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?

Dense but largely purposeful: the parenthetical field list and the return note both earn space. The '§1.1' section reference is opaque without external documentation, and the workflow-mode clause is appended in a way that reads as an afterthought rather than structured.

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?

Because an output schema exists, the description needn't detail return values, and it does sketch the field set for a nested free-form payload. Still, for a mutation tool with no annotations, unclear payload nesting, and no sibling routing, an agent is left guessing about a nontrivial amount.

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% and the only schema property is a free-form 'payload' object, so the description's field enumeration (point_id*, workflow*, question*, kind, options*, etc.) is the sole source of parameter meaning and is genuinely valuable. However, the asterisks marking required fields are never explained, and 'fields at top level' conflicts with the schema's required 'payload' wrapper, leaving real ambiguity about how to shape the call.

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: create or update a decision point, and adds a second mode (type: workflow registers a workflow record). The verb and resource are unambiguous, but the two modes are packed into one tool without saying which one an agent is choosing, and nothing distinguishes it from the many dm_*/do_* siblings beyond the name.

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 dm_register rather than dm_decide, dm_record, or do_register, nor on create-vs-update behavior. The only conditional is 'With type: workflow', which explains an internal mode rather than tool selection context.

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 supplied, so the description carries the full burden. It implies a read-only reporting operation and discloses the metric categories returned, but says nothing about permissions, side effects, rate limits, or pagination, and the '(§15.8)' reference is opaque without the source document.

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?

It is short and front-loaded with the resource and input shape, but the telegraphic style ('auto share', '§15.8') reads as jargon shorthand that an outside agent cannot fully parse. Every line carries content, but the cryptic section reference and unexplained terms cost clarity.

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 input shape is covered despite the opaque schema. What is missing, given a crowded sibling set with dm_/do_ pairs and no annotations, is any routing guidance or behavioral caveats that would let an agent choose and call this correctly.

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% with a single opaque 'payload' object, so the description is doing real work by disclosing the payload shape: a list of point_ids and a format field with json|md options. That is genuinely additive over the schema, though it does not mark which keys are optional or how multiple point_ids combine.

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 says the tool produces 'Per-point metrics' and enumerates the metric families it covers (agreement, coverage, auto share, audits, savings, drift, promotion blockers), which gives a reasonable sense of the output. However, it never names a verb for the operation and never distinguishes this from sibling reporters like do_report or dm_export, so an agent cannot confidently pick it apart from them.

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 only usage hint is 'With workflow, the one-turn workflow report (§15.8)', which gestures at a mode without saying when to choose it or what 'workflow' means here. There is no explicit when-to-use, when-not-to-use, or alternative-tool guidance against the many sibling report/export tools.

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 disclose meaningful behavior: a smoke run precedes a "paid-gated full job" (cost implication), repeat calls act as a status poll (stateful, non-idempotent feel), and the local path returns metrics plus a model card. It does not state permissions required, whether a launched job can be cancelled, or what force/training_free_confirmed actually override.

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?

Compact and front-loaded: purpose first, then payload, then the two execution paths. The semicolon-chained sentences and unexplained jargon ("JEV probe", "joining points") make it slightly harder to parse than it needs to be, but nothing is padded.

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 only be named, which they are (metrics + model card). Given a fully opaque nested payload and zero annotations, the description supplies enough for a correct call in either mode; the remaining gaps are the semantics of force/training_free_confirmed and any polling cadence.

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 schema is a single opaque `payload` object with 0% description coverage, so the description's inline enumeration of point_id (required), dry_run, confirm, training_free_confirmed and force is the only documentation available and is genuinely load-bearing. Meaning is spelled out for dry_run and confirm, but force and training_free_confirmed are listed without explanation, leaving their effect to be guessed from the names.

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 ("Train the decision model for a point") and distinguishes two execution modes (local probe vs. tiered trainer). It does not, however, differentiate itself from near-duplicate siblings such as do_train or dm_plan_run, leaving the dm_/do_ split to inference.

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?

Describes an implicit workflow: dry_run to see the estimate and joining points, confirm to launch, repeat calls to poll. That is actionable sequencing an agent can follow. It stops short of explicit when-not guidance or naming an alternative tool for planning-only or status-only needs.

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 supplied, the description carries the full burden and does disclose the conditional return contract: first call yields rubric + candidate_schema + hints, subsequent calls with candidates yield score and verdict per candidate. It does not say whether the tool is read-only or persists anything server-side (the do_* family suggests state changes), leaving a meaningful gap.

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 dense sentences with the purpose front-loaded and no filler; the pseudo-schema notation packs the payload contract compactly. The bracket/pipe notation is slightly cryptic on first read but earns its space.

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 nested-payload tool with an output schema already present, the description covers the payload shape and the two-phase invocation well enough to call it correctly. Remaining ambiguity about enum-like values ('kind') and candidate formatting is minor but real.

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 schema is a single opaque 'payload' object with additionalProperties:true and 0% description coverage, so the description must compensate and does: it spells out the nested shape {workflow: {kind, text|path}, [traces: {path}], [candidates]} with optional fields bracketed. It stops short of enumerating valid 'kind' values or the candidate object format.

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 opens with a specific verb+resource: 'Find decision points in a workflow', which is far more informative than the opaque name do_analyze. It does not, however, distinguish itself from the many similar siblings (dm_analyze, do_extract, do_decide), so an agent must infer the difference.

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 implicitly defines a two-step usage pattern (call first without candidates, then again with candidates), which is useful procedural context. But it never states when to choose this over dm_analyze or do_extract, nor any prerequisites or exclusions.

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 supplied, so the description carries the full burden; it does usefully declare the operation is read-only and hints at the returned status vocabulary (on|off|blocked(reason)) and gating concept. It says nothing about permissions, whether the payload requires a specific autopilot identifier, or how large the eligible-point list can get. Adequate but far from complete for an annotation-free tool.

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 dense sentence with the read-only qualifier front-loaded and the return contents enumerated in priority order. Every clause carries information; the only minor redundancy is re-describing return values that an output schema already covers.

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 spelling out return contents is largely redundant, while the genuinely opaque 'payload' parameter and the do_/dm_ autopilot_status duplication go unaddressed. The definition is callable but leaves an agent guessing about how to form the payload.

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?

There is a single required 'payload' object with 0% schema description coverage and additionalProperties=true, so the schema explains nothing. The description mentions 'eligible points' and 'hashes' but never says how to scope the request through payload (e.g. which autopilot or point set to query). It adds some domain vocabulary but no usable parameter meaning.

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 opens with a specific verb+resource statement, 'Autopilot state (read-only)', and enumerates what it reports (approved/current autopilot hashes, eligible points, per-point status and gate). That clearly separates it from action-oriented siblings such as do_decide, do_promote and do_plan_run. It does not, however, differentiate itself from the near-identically named sibling dm_autopilot_status, leaving that ambiguity unresolved.

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 the obvious alternative dm_autopilot_status or of what prerequisite state (a registered/planned autopilot) makes this call meaningful. Usage is only inferable from the name and the word 'state'.

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. It usefully reveals the mode-dependent control flow (who makes the decision, and that recording is a separate do_record step, implying do_decide itself does not persist), plus what the response contains. It does not state permissions, side effects, idempotency, or what happens when no allowed_options match.

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?

It is short and front-loads the purpose, then moves to input, output, and mode behavior in a predictable order. However the telegraphic brace notation and single-letter abbreviations make it cryptic rather than crisp; several sentences are terse to the point of ambiguity.

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 restatement is redundant rather than necessary, but the mode semantics fill in behavior the schema cannot express. For a decision tool that branches into a follow-up do_record call, the description still leaves gaps: what teacher_cost changes, how probabilities/confidence should influence the agent's choice, and when auto/rule mode applies.

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% and the schema is a single opaque `payload` object with additionalProperties true, so the description's field list (point_id required, context required, teacher_cost optional) is the only parameter documentation that exists. That is a meaningful addition, but it gives no types, formats, or meaning for each field — context and teacher_cost are left entirely unexplained.

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?

"Ask for a decision" names a resource (a decision) but the verb is abstract — it does not say whether the tool computes a decision, records one, or requests one from the caller. The input/output signature and the mode branches add concrete shape, but there is no differentiation from the sibling dm_decide, which by name is the obvious alternative.

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 gives per-mode guidance: in teacher mode the agent should decide itself and then call do_record, and in auto/rule mode it should use the returned choice. This is real when-to guidance for the follow-up call, but there is no statement of when to choose this tool over dm_decide or do_analyze, and no exclusions.

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 full burden. It does disclose the output format (JSONL), the fact that a path is written (an implicit side effect), and a privacy gate requiring explicit confirmation. It says nothing about overwrite behavior, whether path is a file or directory, or what permissions are required for private points, which leaves meaningful behavioral gaps for a write-side tool.

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 core purpose and the argument shape front-loaded before the conditional rule. Every clause carries information an agent needs.

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. However, for a tool that writes to a path with a privacy gate, the description should say whether an existing file is overwritten, what 'labelled rows' scopes to, and whether point_id accepts one id or many — none of which is covered by the opaque payload schema.

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 is a single opaque 'payload' object with additionalProperties:true and 0% description coverage, so the schema documents nothing. The description compensates substantially by naming point_id and path as required and confirm as optional, plus the conditional rule that private points need confirm:true. It stops short of giving types or path format, which is why it is not a 5.

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 plus the output format: 'Export labelled rows as JSONL'. That is far more concrete than the bare name. It does not, however, distinguish itself from the near-identical sibling dm_export, so an agent cannot tell which one to pick from the description alone.

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?

Provides one real precondition — private points require confirm:true — which is genuine usage guidance. It gives no when-to-use versus when-not-to-use guidance and never mentions dm_export or do_extract, so the routing decision among 25 siblings is left entirely 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?

No annotations are supplied, so the description carries the full behavioral burden. It does disclose the stateful two-phase pattern (Call 2 requires the extraction_id issued by Call 1) and enumerates rejection behavior ("one code per check") and jev_disagreements, which is useful. It says nothing about side effects, permissions, idempotency, or what happens if Call 1 succeeds but Call 2 is never made.

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?

Purpose is front-loaded and there is no filler, but the brace/bracket shorthand is hard to parse and forces the agent to decode notation rather than read prose. Terms like jev_disagreements and extractor_local appear without expansion, costing more in comprehension than is saved in length.

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 yet the description partially restates return values rather than adding interpretation. For a multi-call, nested-payload tool with zero schema coverage, it covers the field list adequately but omits how the two calls relate operationally (timeouts, retry, whether Call 2 is mandatory) and what the required 'extractor' identifier must be.

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% — the only declared parameter is an untyped 'payload' object with additionalProperties true — so the description is the sole source of field information. It compensates well by enumerating the payload keys for both calls and marking required fields with asterisks (extraction_id*, extractor*, records*). It still leaves opaque fields such as contributor_off_confirmed, extractor_local, and new_points unexplained.

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 names a specific verb and resource: "Extract decision labels from a one-turn transcript". It also discloses a non-obvious structural trait (two required calls), which helps an agent understand this is not a single-shot extract. It does not, however, differentiate the tool from near-name siblings like do_analyze or do_decide, and "decision labels" is left undefined.

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 implies usage through the call sequence — Call 1 first, then Call 2 with the returned extraction_id, plus a pass:2 audit variant. That is procedural guidance rather than selection guidance: nothing says when to reach for do_extract instead of do_analyze or do_decide, or what preconditions must hold before Call 1.

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 disclosure burden. It implies a write ("Attach", "records") and hints at two distinct modes (decision outcome vs plan check), but says nothing about idempotency, overwrite behavior if an outcome already exists, required permissions, or side effects. The mutual exclusivity of ok and correct_choice is the only real behavioral fact conveyed.

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 text is short with no filler, but the structure is fragmentary: a bare imperative, then a bracketed field list, then two trailing clauses. The plan_id mode is appended after the input enumeration rather than integrated, forcing the reader to reconcile it with the list above.

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 described, which relieves some burden. But for a mutation tool with zero annotations and a fully undocumented nested payload object, the description should explain the meaning of the flags and the consequences of recording an outcome; it only partially does so.

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% and the only schema property is an untyped `payload` object, so the description does meaningful work by naming decision_id (required), ok, correct_choice, and note. However it never explains what ok or correct_choice actually mean or their types, and it introduces plan_id in the second sentence without listing it among the inputs — creating ambiguity about whether it is a payload field or a top-level argument.

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?

"Attach the real outcome" states a verb and object but is cryptic in isolation — it does not say outcome of what (a decision, per the decision_id field) or how it differs from siblings like do_record, do_decide, or dm_outcome. The parenthetical field list and the plan_id clause give a partial picture of the resource, but an agent cannot cleanly separate this tool from its many do_*/dm_* neighbours.

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 gives input-shape constraints ("Either ok or correct_choice may be given") and one conditional mode ("With plan_id + ok, records a user check result for a plan"), but these are preconditions, not when-to-use guidance. It never says when to call do_outcome versus do_record, do_decide, or do_report, and offers no exclusions or ordering advice.

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. "Record" implies a write, and the sentence about running the workflow check surfaces a genuine, non-obvious side effect, which is real value. However it does not say whether recording is idempotent, what the check does on failure, whether an existing result is overwritten, or what permissions are needed.

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 purpose and then the field list, with no filler. The brace-and-asterisk notation is compact but slightly cryptic and assumes the reader knows the convention for required versus optional keys.

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 described. But for a mutation-style tool in a large namespace of near-duplicate do_/dm_ siblings, the description never distinguishes itself from dm_plan_result and never explains the meaning of trial_id/pair_id/arm or the deterministic-check trigger condition, leaving meaningful gaps.

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% and the payload is a bare additionalProperties object, so the schema conveys nothing. The description fully compensates at the structural level by enumerating plan_id as required and transcript, final_output, cost, conflict, trial_id, pair_id, arm as optional. It does not explain what pair_id, arm, or conflict mean or what types they take, leaving some semantic gaps.

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?

"Record a planned run's result" gives a specific verb and resource, and the name-plus-description pair makes the plan-result trailing step understandable. It stops short of differentiating itself from the near-identical sibling dm_plan_result or from do_record, so an agent still has to infer which of the pair to call.

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 when-to-use guidance at all: nothing says whether this is called after do_plan_run, whether it can be called repeatedly for the same plan, or how it relates to do_record/do_outcome. The only conditional statement ("Runs the workflow check when deterministic") describes internal behavior rather than guiding tool selection.

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 it does disclose the shape of the outcome (recommendation plus prompt_addendum or would_have), which tells the agent this is a decision-assist step rather than a mutation. It stops short of saying whether the call is read-only or has side effects, or what trial/pilot_force actually change at runtime.

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, front-loaded with the purpose, then the input contract, then the return contract — a sensible order with no filler. The bracket-and-asterisk notation is dense but readable for an agent parsing structure.

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 description needn't document return values in depth and it correctly just names the outcome categories. Its gap is the ten-field nested payload, whose field meanings and mode interactions are undocumented anywhere given 0% schema coverage, which is a real shortfall for a tool of this complexity.

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% and the schema exposes only an untyped 'payload' object, so enumerating the payload keys with required (*) and optional ([..]) markers is genuine compensation that the schema alone does not provide. But it names keys without explaining them: what 'context_source' selects, how 'run_model' differs from 'cheap_model', or what 'pilot_mode'/'pilot_force' toggle is left to guesswork.

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 verb and scope are present ('Plan one-turn work'), and the description reveals it produces a recommendation of inject/downgrade/none plus a prompt addendum. However 'one-turn work' is internal jargon, and nothing distinguishes it from the sibling dm_plan_run or do_plan_result, so an agent cannot confidently pick it over its near-namesakes.

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 when-to-use guidance at all: no statement of sequencing relative to do_plan_result, dm_plan_run, or do_decide, and no indication of preconditions. The optional [trial] and [pilot_mode] flags hint at experimental versus production use but never explain which to pick.

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 burden and does disclose meaningful behavior: this is a state-changing move with per-phase prerequisites, a confirm gate, and a human-in-the-loop recommendation for serve. It says nothing about reversibility, permissions, failure behavior, or what happens to the point's current state, which matters for an unannotated mutation tool.

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 signature is front-loaded, which is good, but the remainder is a single overloaded run-on of parenthetical conditions and internal cross-references that an unfamiliar agent cannot resolve. Nothing looks purely redundant, yet the density and section-number shorthand hurt scannability.

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 covered, and the description does address the biggest gap by enumerating payload fields despite a fully opaque schema. Still, the plan_phase and workflow/downgrade variants are gestured at via §15.6/§15.8 without explanation, and no annotation coverage exists to backstop the mutation semantics.

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% and the schema exposes only an untyped 'payload' object with additionalProperties, so the description is the sole source of parameter meaning. It compensates well by naming the required fields (point_id, phase), giving the phase enum values, noting confirm as optional, and mentioning plan_phase / workflow+downgrade modes, though it leaves those alternate fields' structure undefined.

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 opens with a concrete verb and resource ("Move a point") and enumerates the controlling fields (point_id, phase with the four allowed values), so the agent knows exactly what operation this performs. It is distinguishable from siblings like do_train or do_decide, though the meaning is partly carried by opaque internal section references (§6.4, §15.6, §15.8).

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 gives real gating conditions for two modes: shadow requires a trained local_legacy probe or hosted key plus budget plus remote_ok; serve requires the §6.4 checks plus confirm:true and advises asking the user first. However, it never names an alternative tool or states when not to use this one, so routing guidance is implied rather than explicit.

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 supplied, so the description carries the full behavioral burden. It does not say whether recording is idempotent, whether it mutates state permanently, what permissions are needed, or how validation failures surface; only the allowed_options constraint is disclosed.

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 text is front-loaded and free of filler, moving from purpose straight to the payload signature. It is arguably too terse rather than bloated, but every sentence conveys 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. However, for a mutation tool with no annotations and a nested free-form payload, the description omits error behavior and the source of allowed_options, leaving real gaps for an agent.

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 schema exposes only an opaque 'payload' object with zero description coverage, so the description is the sole source of parameter meaning. It usefully spells out the payload shape with required markers (decision_id, choice) and an optional field (teacher_cost), though it does not explain what teacher_cost represents or where allowed_options comes from.

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 concrete verb and object ('Record the teacher's choice'), so an agent knows it writes a decision selection. It does not distinguish itself from near-identical siblings such as do_decide, dm_record, or do_outcome, 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?

There is no when-to-use guidance, no mention of which sibling to prefer for adjacent tasks, and no stated prerequisites. The only rule given ('choice must be in allowed_options') is a validation constraint rather than 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 exist, so the description carries the full behavioral burden. It does disclose that the result includes the stored point and a paste-ready snippet, but it omits whether an update overwrites or merges existing fields, what permissions are required, what validation errors look like, and how the 'irreversible' flag actually changes behavior — significant gaps for a create-or-update mutation.

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 verb and resource are front-loaded, which is good, but the bulk is a single dense parenthetical of field names that reads as a data dictionary rather than prose. It is compact but not well structured, and the reader must unpack the nested clause to find the workflow-record variant.

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 values need not be explained, and the description wisely focuses on inputs. Still, for a create-or-update tool with a nested free-form payload and no annotations, missing details about update semantics, field placement, and the two operational modes leave an agent under-equipped to invoke it correctly on the first try.

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 schema exposes a single opaque `payload` object with 0% description coverage, so the description must compensate, and it partly does by naming the expected fields and asterisk-marking the required ones (point_id, workflow, question, options, context_fields). However, it says these live 'at top level' while the schema nests everything under `payload`, leaving the actual key placement ambiguous, and types/formats for kind, rules, or data_class are never explained.

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 pair: 'Create or update a decision point', and enumerates the domain fields involved. An agent knows what the tool produces (a stored point plus a call snippet). It never distinguishes itself from the near-identical sibling do_record or the dm_register variant, so it stops 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?

There is no statement of when to choose do_register over do_record, dm_register, or the do_/dm_ prefixed siblings that clearly shadow it. The only implicit guidance is the branch 'With type: workflow, registers a workflow record', which describes a mode rather than a selection criterion, and no exclusions or prerequisites are given.

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 supplied, so the description carries the entire burden of behavioral disclosure, and it does not state that this is a non-mutating read, whether permissions or scopes are required, or whether results are paginated or cached. The enumeration of metric categories is useful context but is content scope rather than behavioral context, and the opaque "§15.8" reference conveys nothing to an agent without external documentation.

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 definition is short and front-loads the metric inventory, but it is written in telegraphic fragments and includes a documentation section reference that does not parse for an agent. Nothing is gratuitously repeated, yet the terseness costs clarity rather than buying it.

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 tool's surface is simple with only one parameter. What remains missing is precisely what the free-form payload schema cannot provide: required subfields, id cardinality, format default, and the read-only safety profile that the absent annotations leave 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?

The input schema is a single free-form "payload" object with zero description coverage, so the description is the only source of parameter meaning, and it does add real value by decomposing the payload into point_id and format with the json|md values. It stops short of saying whether point_id is a single id or a list, whether it is required, or what the default format is, so the compensation is partial.

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 says it produces "per-point metrics" and enumerates the metric families (agreement, coverage, auto share, audits, savings, drift, promotion blockers), so the resource is identifiable. But the verb is only implied through the tool name, and nothing distinguishes it from the sibling dm_report, which the agent cannot rule out on the basis of the text alone.

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 guidance and no named alternative, even though dm_report and do_analyze are obvious competitors in the sibling set. The only routing hint is the fragment "With workflow, the one-turn workflow report (§15.8)," which signals a conditional mode without saying when an agent should pick that mode over plain per-point metrics.

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 supplied, the description carries the full burden and does well: it discloses two execution paths (local JEV probe vs. tiered trainer), that confirm triggers a paid-gated job after a smoke run, and that repeated calls are polling rather than re-training. It omits permission requirements, failure behavior, and what force or training_free_confirmed override.

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?

Dense and front-loaded: the purpose leads, the payload signature follows, then path behaviors. Bracket notation for optional fields is efficient. Some jargon ('JEV probe', 'Tiered path with a trainer') costs a little clarity 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. For a cost-incurring mutation with a nested, undocumented payload, the description covers the critical decision points (estimate vs. launch vs. poll) and two execution modes. Only the meaning of the override flags is left uncovered.

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% and the sole parameter is an open 'payload' object, so the description must compensate. It does list the payload keys (point_id required, dry_run, confirm, training_free_confirmed, force), which is essential, but it never explains the semantics of training_free_confirmed or force, leaving two flags opaque.

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: 'Train the decision model for a point.' An agent can tell what the tool produces. It does not, however, differentiate itself from the sibling dm_train, which on name alone looks like the same operation, leaving ambiguity about which 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?

Gives a clear invocation sequence: dry_run to see the estimate and joining points, confirm to launch (smoke first, then the paid-gated full job), and repeat calls to poll status. That is real when-and-how guidance, though it offers no exclusions or comparison against the dm_* siblings.

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