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

Goes well past the readOnly/destructive annotations: it explains that closed days refuse writes with the code `closed`, that no one including the owner can add/edit/move/delete hours on or before lockedUntil, that a timer cannot start when the lock reaches today, and that any project member can read the rules. That downstream-effect and permission context is exactly what annotations cannot convey.

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 scope statement is correctly front-loaded, but the body is one very long sentence with heavily nested parentheticals ('...the last closed day: nobody, the owner included, can add, edit, move or delete hours dated on or before it, and a timer cannot start while it reaches today'), which makes it dense to parse. The content earns its place but the packaging does not.

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?

There is no output schema, so the description must carry the return contract, and it does: per-mode it enumerates lockedUntil, editWindowDays with sentinel semantics (0 = only today, null = no limit), today in the user's time zone, plan entitlement, and for boardId ownership, earliest editable day, and timer-start eligibility. Nothing an agent needs to interpret the result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already documents boardId as a project the user belongs to with 'omit for own rules,' so the description cannot add much on the parameter itself. Its value lies in describing what each mode returns rather than the parameter's syntax, so it sits at the baseline.

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 and resource ('Reads the rules that close logged hours') and immediately splits the tool into two distinct modes keyed on boardId, so an agent can tell exactly which behavior it will get. The named fields (lockedUntil, editWindowDays) further pin down what 'rules' means here versus other read tools like get_project_settings.

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 conditional guidance: 'Without boardId: ... With boardId: ...' and 'Omit it for the user's own rules,' which is enough for an agent to pick the right mode. It does not name the mutation counterpart (set_time_rules) or state when to prefer other tools, so the routing is clear but not exhaustive.

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