dm_train

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.