log_run

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

With only weak annotations (all hints false), the description carries the behavioral burden and delivers richly: it discloses that the tool converts units itself ('The tool converts once before storage, so this overrides any wording that asks you to do the arithmetic'), that logging 'writes the completed run and returns a card marker for in-app editing', and imposes anti-fabrication constraints ('Never invent sensor data or splits', 'do NOT call it easy merely because it was a run'). These go well beyond what readOnlyHint=false and idempotentHint=false convey. No contradiction with 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?

The description is long (~250 words) but earns its length given 19 parameters and two operational modes. It is well-organized with labeled sections (UNIT INPUTS, intent, RUN TYPE, DETAIL) and front-loads the most critical instruction (unit handling) before anything else. Minor deduction: some redundancy with schema descriptions — the run_type and splits/segments 'never invent' constraints appear both in the schema and the description.

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 tool with 19 parameters, two intents, and five enums, the description covers the decision-critical ground: unit conversion policy, the log-vs-plan distinction with required fields, run-type classification guardrails, and data-fidelity constraints. An output schema exists, so return values need not be described. Minor gaps: no explicit guidance on ambiguous cases (e.g., a run that might be both a plan and a log) and some per-field sourcing rules are left to the schema — but nothing an agent needs 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?

Though schema coverage is high (89%), the description adds critical cross-parameter semantics the schema only references: the UNIT INPUTS paragraph explains the pairing rule ('when they gave kg / km / cm set input_weight_unit / input_distance_unit / input_length_unit in that same object. Omit the companion when the number is already lb / mi / in'). It also adds intent-specific required fields for log (date, distance_mi, duration_sec) that the schema does not state, and clarifies run_type classification guardrails. This far exceeds the baseline 3 for high schema 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 states a specific verb and resource: 'Create an editable running card. Use for a completed run OR a future run plan.' It further distinguishes two intents — log (the run happened) vs plan (the run has NOT happened) — which sets it apart from nearby siblings like log_workout, log_wearable, and log_rest_day. An agent can clearly identify this as the run-specific card creator without opening the schema.

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 explicit 'when' guidance: use for a completed run OR a future run plan, with a hard rule that a future run must never go into completed history. It also clarifies defaults (log is default) and mode-specific required fields. However, it does not explicitly name alternatives or exclusions (e.g., 'use log_wearable for synced wearable data' or 'use update_workout to modify'), so routing between siblings is left partly to inference.

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