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

Annotations already declare a non-destructive, idempotent mutation, so the bar is lower. The description adds real behavioral context beyond them: the session 'is classified again after a change' (a side effect on derived classification) and the end-before-start rule implying an overnight span. It does not mention permissions or how partial updates behave.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the verb and resource, then the field list, then the usage note. The long field enumeration is dense but earns its place across 15 parameters, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter mutation with no output schema, the description covers what can be changed, when to reach for it, and the reclassification side effect. A reader still has to consult the schema for enum values, defaults and id/format details, which is acceptable but leaves minor 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 60%, so the description carries part of the burden. It groups the mutable fields into one readable list and adds genuine semantics the schema lacks: the midnight-crossing rule for a start/end whose end precedes the start. Otherwise the field enumeration largely mirrors schema property 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 (fix/edit) and resource (session) and enumerates exactly what is editable: start, end, task, area, project, lever, step, plan item, summary, outcome, attention share, weight. It also scopes the target as 'running or finished', which cleanly separates it from add_session, delete_session, start_session and stop_session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit triggering conditions: 'Use it when a timer was forgotten or a session was labelled wrong.' That is a clear when-to-use signal. It stops short of naming alternatives (e.g. split_attention for dividing attention, stop_timer for live timers) or stating when-not to use it, so no full routing guidance.

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