devBoard

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

Annotations already declare non-read-only, non-idempotent, non-destructive writes; the description adds context the annotations do not carry — that @[Name]/@[email] mentions trigger notifications to other people and that body content is parsed as Markdown. That notification side effect is the key behavioral fact an agent needs before posting on someone's behalf.

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 short, front-loaded fragments with no filler: action first, then mention/notification semantics, then content format. Nothing is repeated from the title or schema, and the ordering puts the most decision-relevant information 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?

With an output schema present and annotations covering the safety profile, the description only needs to carry action, side effects, and content format — all of which it does. Minor omissions like error behavior on an invalid key or permission requirements keep it short of a full 5.

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 both parameters (key 'Like APP-123', body 'The comment'), so the baseline is 3. The description goes beyond the schema by specifying that body is Markdown and that mention syntax is @[Name] or @[email], which materially affects how the body should be constructed.

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 resource — commenting on an item — and clarifies authorship with 'as you', so the agent knows this creates a comment attributed to the authenticated user. It does not name or contrast with edit_comment or delete_comment, so the sibling differentiation is left to the tool name 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?

Usage is only implied: the action of commenting makes the when obvious, but there is no guidance on prerequisites (e.g. the item key must exist), no mention of when to prefer edit_comment over posting a new comment, and no exclusions. Adequate for a simple append operation but with a clear gap.

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?

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower, and the description adds a genuine side-effect disclosure: that remind_at causes a reminder to pop on the user's devices. That outcome is not derivable from the annotations or schema. It stops short of covering failure modes or whether the to-do is synced across devices.

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, and the core purpose is front-loaded ahead of the optional-parameter behavior. Every clause carries 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?

The tool is simple (2 params, 1 required, no nesting), annotations carry the safety profile, and an output schema exists so return values need not be described. The description covers purpose and the reminder side effect; the only gap is the implicit distinction between personal to-dos and workspace items created by create_item.

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%, so the baseline is 3 and both parameters are already documented in the schema. The description adds meaning beyond the schema by explaining the observable effect of remind_at (a reminder firing on devices), which tells the agent what setting that field actually accomplishes.

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 ('Adds to your personal to-do list'), which cleanly separates it from siblings like create_item, add_comment, and update_todo. It does not, however, explicitly name an alternative or state why a personal to-do differs from a workspace item, so the differentiation is implicit rather than spelled out.

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 phrase 'your personal to-do list' implies the usage context (personal to-dos rather than workspace items or comments), but there is no explicit when-to-use, when-not-to-use, or named alternative such as update_todo or create_item. Usage must be inferred from the scope wording.

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?

Annotations already declare a non-destructive, idempotent write, but the description adds genuinely useful context beyond them: the cascade to subtasks and the reversibility via restore:true. It still says nothing about permissions or where archived items go.

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, front-loaded with the action and scope, followed by the reversibility guarantee. Every clause carries information; 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?

With an output schema present, return values need not be described, and the description covers the two things an agent most needs: the subtask cascade and reversibility. Only permission/authorization context 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%, so baseline is 3, but the description adds semantic meaning by explaining that restore:true reverts the archive rather than just naming it. The 'key' parameter remains purely schema-documented.

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 ('takes an item... off the board') and adds the important scope detail that subtasks are included. It implicitly contrasts with deletion ('Nothing is deleted'), which helps distinguish it from destructive siblings, though it doesn't name a specific sibling tool.

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?

Usage is implied: archive rather than delete, and use restore:true to undo. There is no explicit statement of when to prefer this over alternatives or any preconditions, so the agent must infer the routing decision.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety is largely covered. The description adds real behavioral context beyond that: the parent-derived hierarchy rule, the default-column landing behavior, and the status/category override, though the return-value note is partly redundant given the output schema.

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?

Four tight sentences, front-loaded with the core purpose and zero filler. The trailing sentence about the returned key and git branch name is low value since an output schema already exists, keeping it just short of ideal.

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?

With 15 parameters, an output schema and full annotations, the description covers the non-obvious parts (hierarchy inheritance, default column, status/category precedence) well. It omits any note that this is non-idempotent and will create duplicates on repeat calls, which is the one behavioral caveat an agent should have.

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%, so the baseline is 3, but the description adds relational meaning the schema does not: that supplying parent determines both project and level, and that status or category overrides the default column. That interaction between parent, project and level is exactly the cross-parameter semantics an agent cannot infer from per-field descriptions.

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 first sentence gives a specific verb ('Creates') plus the exact resource variants it produces (epic, task, subtask), which immediately separates it from siblings like create_label and create_release. An agent can identify the operation and its scope 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?

It states the minimal invocation conditions ('only title and a project are needed') and the alternative path ('with parent, the project and level follow from it'), which is genuine routing guidance for a 15-parameter tool. It does not, however, contrast this with update_item or move_item for objects that already exist, so it falls short of explicit when-not 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a valuable behavioral fact the annotations do not carry: the operation requires admin privileges. It stops short of covering duplicate-name behavior, which matters given idempotentHint=false.

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 with zero waste. The action is front-loaded and the permission constraint follows immediately. Every sentence earns its place.

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 schema fully documents parameters while annotations cover the safety profile. The only meaningful gap is what happens when a label with the same name already exists, which is relevant given idempotentHint=false.

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 100%, with all three parameters documented including format hints ('#RRGGBB', 'like "bug"', 'A project key'). The description adds nothing about parameters, so the baseline of 3 is appropriate when structured fields do the heavy lifting.

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: 'Adds a label to a project.' An agent can immediately tell this creates a label scoped to a project. It does not differentiate from siblings, but no sibling tool overlaps with labels, so differentiation is largely moot.

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?

'Admins only' is a genuine prerequisite that constrains who should call it, which is real usage guidance. However, the description names no alternatives and gives no guidance on when to create a label versus using existing ones, leaving usage largely implied.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the agent knows this writes but does not destroy. The description's added value is the admin permission requirement, which is not captured by annotations, but it says nothing about duplicate release names, side effects, or confirmation behavior.

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 fragments, front-loaded with the action and immediately followed by the constraint. Every word earns its place, though the terseness borders on under-specification for a mutation tool.

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?

With an output schema present the description need not explain return values, and all three parameters are documented. What is missing for a creation tool is behavior on duplicates, error conditions, and any workflow context relative to ship_release, leaving it adequate but thin.

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 100%, so the schema already documents name, project and target_date with formats. The description adds no parameter detail beyond the schema, which is the expected baseline when the schema does the work.

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?

"Plans a release in a project" gives a specific verb plus resource and scope, and "Plans" usefully distinguishes it from ship_release. It stops short of explicitly naming that sibling, so an agent infers rather than is told the boundary.

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?

"Admins only" is a real usage gate the agent can act on, which is better than nothing. However there is no guidance on when to plan a release versus calling ship_release, and no prerequisites such as whether the project must already exist.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: the ownership restriction and the fact that "the timeline keeps an empty placeholder," i.e. the deletion is soft/visible rather than a clean removal. That is genuinely new information an agent cannot get from structured fields.

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 action front-loaded and the two caveats (permissions, placeholder) following. Every clause carries 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?

For a one-parameter destructive tool with an output schema, the description covers the essentials: action, authorization scope, and the post-deletion side effect. It does not clarify whether the comment can be restored or how the empty placeholder affects subsequent reads, a minor gap.

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 100% and the single parameter (comment_id) already documents its source ("from get_item"). The description adds nothing about the parameter, so the baseline 3 applies.

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 ("Removes one of your comments") and immediately scopes ownership with the admin exception, which cleanly separates it from edit_comment and add_comment in the sibling list. An agent can identify the operation 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 parenthetical about admins removing anyone's comments gives real authorization context for when the call will succeed, but there is no explicit guidance on when to delete vs. edit (edit_comment) or what conditions should trigger deletion. Usage is implied rather than stated.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. "For good" adds a modest irreversibility nuance beyond that, but the description says nothing about auth requirements, cascade effects, or whether the deletion can be recovered.

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?

One short, front-loaded sentence with the destructive verb first and no wasted preamble. The colloquial "for good" is a small stylistic cost but it does double duty as a permanence signal.

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 and the lone parameter is fully documented, so return-value and parameter explanations are not owed. However, for a permanently destructive tool sitting beside edit_time_entry, the absence of any routing guidance leaves a real gap an agent could get wrong.

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 100% for the single entry_id parameter ("From timesheet."), so the schema carries the parameter burden. The description adds no format, provenance, or constraint detail beyond it, making 3 the correct 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?

States a specific verb ("Removes") and resource ("one of your time entries"), so the action is unambiguous. It does not name the coexisting sibling edit_time_entry, which is the obvious alternative an agent might need to consider, so it stops short of full sibling differentiation.

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 use this versus edit_time_entry, no prerequisites, and no conditions or exclusions. The agent gets the what but nothing about the surrounding decision 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is fully covered. The description adds only the phrase "for good," reinforcing permanence beyond what the annotations literally state, but says nothing about permissions, error behavior on missing IDs, or side effects.

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 front-loaded sentence with zero filler. The idiomatic "for good" is compact but slightly informal and less precise than an explicit statement of permanent deletion.

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 and annotations cover the mutation profile, so the description need not explain return values or destructiveness. The remaining gap is the absence of any disambiguation from archive_item, which matters for a single-param delete tool in this sibling set.

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 100% and the single parameter carries the meaningful hint "From list_todos." The description contributes no parameter detail, so the baseline of 3 applies since the schema does all the work.

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 ("Removes") and resource ("one to-do"), cleanly distinguishing it from add_todo, update_todo, and list_todos. It does not, however, differentiate it from the sibling archive_item, which is the realistically confusable alternative given "for good" implies hard deletion.

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 or when-not-to-use guidance, and no alternative is named. An agent gets no signal about whether to prefer this over archive_item or update_todo, which is the key routing decision for a deletion 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?

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds a genuine constraint not present in the annotations: only comments you own can be edited, which is an authorization fact the agent needs.

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 action stated first and the ID provenance second. Nothing could be removed without losing 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 no explanation, and annotations carry the mutation/safety profile. Purpose, ownership scope, and ID source are all present; only the replace-vs-append semantics of "rewrites" is left to inference.

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 100% and both parameters are documented in the schema, so the baseline is 3. The description's "Ids come from get_item" merely restates the comment_id schema description and adds no new syntax or format detail.

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 (rewrites) and resource (one of your own comments), and the ownership constraint separates it from the sibling delete_comment/add_comment set. It stops short of naming an alternative explicitly, so it is clear but not sibling-routing.

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?

"Ids come from get_item" gives a concrete provenance prerequisite for the required comment_id, which is useful usage context. It never states when to prefer this over delete_comment or add_comment, so guidance remains 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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds one genuine behavioral constraint beyond the annotations — that only stopped entries are editable — but omits conflict behavior (e.g., note vs clear_note together) and any permission context.

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 front-loaded sentence with zero filler that states purpose and scope immediately. Nothing to trim and nothing buried.

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 small mutation tool with an output schema and informative annotations, the description is minimally sufficient. It does not address the note/clear_note interaction, permissions, or sibling routing, leaving gaps the annotations cannot fill.

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 100%, so all four parameters (note, minutes, entry_id, clear_note) are already documented in the schema. The description names 'length or note' but does not clarify clear_note or precedence rules, so it adds no meaning beyond the schema 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?

States a specific verb+resource ('Fixes the length or note') applied to a scoped object ('one of your stopped entries'). The 'stopped entries' qualifier implicitly separates it from log_time and start_timer/stop_timer, but no sibling is named explicitly, 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?

The phrase 'stopped entries' weakly implies you may only edit already-completed entries, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as log_time or delete_time_entry. An agent gets no routing help.

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?

Annotations only cover the safety profile (not read-only, not destructive, not idempotent), and the description adds substantial behavior on top: the timer only stops if it is running on this item, the comment is optional, the move target defaults to the first done column and is overridable, and move:false suppresses the move. It does not say what happens if the item is already finished or whether the operation is reversible.

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 primary action first, then the destination logic, then the opt-out. Every clause carries information and nothing is redundant.

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 composite mutation with an output schema (so return values need not be described) and annotations covering safety, the description covers the essential mechanics. Minor gaps remain around preconditions (already-done items, assignment requirement for the timer) and reversibility, but an agent has enough to call 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: move:false explicitly leaves the item in place (the schema only says 'Defaults to true'), and it clarifies how status/category redirect the destination column away from the default done column. That is more than restating the schema.

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 the specific composite operation (stopping the timer, adding a closing comment, moving the item) and its exact destination rule, so an agent can distinguish it from siblings like stop_timer, move_item, or add_comment. The 'wraps an item up' framing plus the concrete side-effect list makes the purpose unambiguous.

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 clear context for when this tool is the right one (closing out an item, with the move:false escape hatch for staying in place), but it never names the alternative tools (stop_timer, move_item, add_comment) an agent might reach for instead, nor states exclusions such as items already in a done column.

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?

Annotations already declare readOnly, idempotent and non-destructive, so a read tool's safety profile is covered. The description adds real behavioral detail beyond them: only the 20 newest comments are returned, include_history appends the change log, and the git branch name is included. It stops short of noting pagination or truncation for the comment set, but the limits it does state are valuable.

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?

One dense sentence, front-loaded with the core action ('One item in full'), followed by a colon-delimited inventory that stays scannable. Every element listed is a distinct returned field, though the length is near the limit for a single 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?

With read-only annotations and an output schema already present, the description does not need to explain return values, yet its field inventory plus the comment-count and history limits make the tool's behavior unambiguous. No gaps that would cause a mis-invocation, only the absence of sibling routing guidance.

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%, so the baseline is 3, and the description earns above that by giving the purpose of each parameter: comment ids are surfaced specifically 'for edit_comment', and include_history is framed as adding the change log. That cross-tool linkage is meaning the schema alone does not supply.

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 retrieval verb and resource ('one item in full') and enumerates exactly what comes back, so the agent knows this is the single-item deep fetch. It does not name a sibling like search_items, so the single-vs-list distinction is implied rather than explicit.

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?

Usage is implied: fetch one item by key when you need its full detail. There is no statement of when to prefer this over search_items, run_view, or my_work, and no note on prerequisites such as knowing the key. Minimum viable context only.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world, so the safety profile is fully covered structurally. The description adds that this is a whole-workspace snapshot rather than a filtered query, which is mild added context, but it says nothing about response size, freshness, or why it should not be re-called.

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?

One front-loaded sentence names the scope and packs the return inventory compactly, followed by a single high-value imperative ('Call once at the start'). No filler sentences.

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-value documentation is not needed, and annotations cover the safety profile. For a zero-parameter bootstrap call the description supplies everything an agent needs: what it returns, when to call it, and how often.

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 tool takes zero parameters, so the schema-driven baseline of 4 applies. The description correctly implies there is nothing to parameterize and that the entire workspace is returned unconditionally.

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 (get) and resource (workspace) and then enumerates exactly what is returned: the user's identity/role/timezone, projects with keys, columns, labels, releases, item types, members, and saved views. That enumeration makes it unmistakable against siblings like get_item or my_work, which return narrower slices.

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?

'Call once at the start' gives explicit timing guidance that is not evident from the schema or annotations. It does not name an alternative tool or state exclusions, but no sibling competes for this bootstrap role, so the guidance is adequate.

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds a genuine behavioral trait not in the annotations: results are returned 'newest first'. It says nothing about pagination behavior, defaults, or how unread state is represented, so it adds modest value over the structured fields.

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 compact sentence, front-loaded with the core framing ('Your inbox') followed by ordering and content scope. Every clause carries information 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?

The tool is simple (two optional params, no nesting) and an output schema exists, so return values need not be explained. The description covers identity, content scope, and ordering, which is adequate for an agent to call it correctly. Only the missing routing to mark_notifications_read keeps it from a 5.

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 100%, with both limit and unread_only documented in the schema itself, so the baseline is 3. The description adds no parameter-level detail beyond the schema (e.g., it never mentions the limit cap or the unread filter), but it also has no obligation to.

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 the resource (notifications), characterizes it as 'your inbox', and enumerates the content types (assignments, changes to your items, mentions) plus the ordering (newest first). This is far more specific than a tautology and helps distinguish it from list_todos or my_work. It stops short of explicitly naming a sibling it is not, so it doesn't reach 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 when-to-use or when-not-to-use guidance, and no reference to the closely related sibling mark_notifications_read, which an agent would need to distinguish viewing from mutating notifications. The phrase 'Your inbox' only weakly implies the usage context, which is the definition of implied rather than stated 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context by disclosing the default filter (open items only unless include_completed), which structured data does not 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?

Two compact clauses with zero waste, and the personal-scope qualifier is front-loaded. It reads slightly telegraphically but every segment carries 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?

With an output schema present, return values need not be described, and annotations cover the safety profile. The only minor gap is pagination or ordering behavior for a list tool, which is neither described nor annotated.

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 100%, so the single parameter is already documented in the schema, and the description only restates its effect. Baseline 3 is appropriate when the schema does the heavy lifting.

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 the verb (list) and resource (your personal to-do list) and distinguishes it from workspace items, which sets it apart from siblings like search_items and my_work. It is clear but stops short of naming the specific sibling alternatives by 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?

The scope note (private to you, not workspace items) implicitly tells an agent when this tool applies versus workspace-search tools, and the default filter behavior is stated. However, no alternative tool is named explicitly and no when-not guidance is given beyond the scope contrast.

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?

Annotations already cover the write-safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description adds a real behavioral detail beyond them: started_at is auto-derived as now minus the duration when 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?

Two short sentences, purpose front-loaded, example embedded, and the parameter default disclosed in the trailing clause. 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?

With an output schema present, return values need no explanation, and all four parameters are fully documented in the schema. The description covers purpose, an example, and the one non-obvious default, leaving little an agent would need to guess.

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 100%, so the baseline is 3; the description adds meaning beyond the schema by documenting the defaulting behavior of started_at (now minus duration). It also embeds an example mapping free-form input to key/minutes, which the schema does not.

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 ("Records time") and scopes it to time that "no timer measured", which conceptually separates it from start_timer/stop_timer siblings. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than read it.

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?

"Records time no timer measured" functions as an implied when-to-use/when-not condition, and the concrete example ("2h on APP-12 yesterday") shows the intended shape of a call. No alternative tool is named, so the routing is contextual 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?

Annotations provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that it affects the 'whole inbox', which is useful scope context. However, it doesn't explain reversibility or what happens to already-read notifications. With annotations covering most behavioral traits, this is adequate.

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?

One short sentence, front-loaded with verb and scope. Every word earns its place. No waste.

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?

A simple, zero-parameter tool with annotations and an output schema. The description covers the core action but doesn't address idempotency, side effects, or use cases. Given the tool's simplicity, it's minimally complete but could be clearer about when to use it.

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?

Zero parameters, so baseline is 4. The description correctly implies a parameterless operation, matching the schema. No additional semantics needed.

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 (marks) and resource (whole inbox / notifications). Clear purpose, but doesn't distinguish from sibling list_notifications, which is functionally opposite. A stronger description would clarify the relationship.

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 guidance on when to use this tool vs alternatives like list_notifications. The description doesn't say whether this is idempotent or what prerequisites exist. An agent must infer usage from the name alone.

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?

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description's 'Moving to the column it is in changes nothing' restates the idempotency the annotation already conveys, adding only light confirmation rather than new behavioral context such as permission requirements or side effects.

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 with no wasted words, and the core action is front-loaded before the target-specification detail. The no-op clause is the only slightly expendable element.

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 no explanation, and the mutation semantics fit the annotations. What is missing is routing guidance against update_item and any note about what a move affects (notifications, ordering), leaving the definition minimally adequate for a 3-parameter mutation 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?

Schema coverage is 100% and the schema already documents all three parameters, including the precedence rules ('Wins over category' / 'status wins over it'). The description echoes the status-vs-category precedence and adds only the minor note that category maps to 'the first column of that kind', so it does not materially exceed the schema.

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 verb and resource ('Moves an item to another column') and clarifies the target may be given as a column name or a category. It does not distinguish itself from the overlapping sibling update_item, which likely also touches an item's status, so sibling differentiation is missing.

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?

Usage is only implied: an agent infers this is the tool for relocating an item between columns. There is no explicit statement of when to prefer move_item over update_item, nor any preconditions (e.g., required permissions or valid column names).

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?

Annotations already establish the safe-read profile (readOnlyHint true, destructiveHint false, openWorldHint false, idempotentHint true). The description adds genuine extra context beyond that: results are computed in the caller's own timezone, are limited to the token's workspace, and that a token cannot enumerate every workspace. It does not mention pagination or result limits, so it is strong but not 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?

It is a single dense sentence with the scope and bucket list front-loaded and no filler. The dash-delimited aside about workspaces is a bit crammed in, but 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?

With an output schema present, return shape need not be explained, and annotations cover the safety profile. The description supplies scope, timezone behavior, and the bucket taxonomy, which is enough for an agent to call it correctly; only the optional project filter goes unmentioned.

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 100% for the single optional 'project' parameter, so the schema already carries the meaning. The description adds nothing about the project filter, so this sits at the baseline rather than above it.

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 the resource (the app's My Work buckets) and enumerates exactly what is returned (overdue, today, thisWeek, later, noDate), so an agent knows this is the personal to-do overview rather than a generic list. It implicitly separates itself from siblings like list_todos and timesheet by scoping to work assigned to the caller. It never states a crisp verb like 'list' or 'retrieve', which keeps it just short of 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 framing 'the answer to what should I do now' hints at the use case, and the workspace restriction clarifies a boundary, but no alternative sibling is named and no when-not-to-use condition is given. It is implied usage rather than explicit routing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds meaningful behavior beyond them: the result is guaranteed to match the app's own filter and sort for that view, and the view name must be sourced from get_workspace. Return format and pagination behavior are left to the schema/output schema.

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?

One sentence, front-loaded with the action and resource, with the discovery hint and the equivalence guarantee packed into a single clause. 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?

With an output schema present, return values need not be explained, and the read-only/idempotent annotations cover side effects. The description supplies name discovery and result-equivalence semantics, which is adequate, though it never mentions pagination or what happens if the named view does not exist.

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 100%, so all three parameters (view, limit, offset) are already documented in the schema, and the baseline is 3. The description's "by name" adds only a small amount of meaning for the required view parameter and says nothing about limit/offset.

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 ("Runs a saved view by name") and clarifies that get_workspace is where view names come from, which separates it from the listing tool. It does not, however, contrast running a saved view with the other retrieval sibling search_items, so differentiation is only partial.

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 parenthetical "(get_workspace lists them)" tells the agent the prerequisite for obtaining a valid view name, which is real usage context. There is no explicit when-not guidance or statement of an alternative path when no saved view exists.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds non-obvious behavior beyond that: AND-combination of filters, default exclusion of done/cancelled items, and default sort by recently-updated. It does not cover pagination behavior, but the key filtering defaults are 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?

Effectively four short sentences, front-loaded with purpose and each sentence carrying distinct information (combination rule, default filtering, default sort, delegation to get_item). No waste.

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?

With an output schema present, return-shape explanation is unnecessary, yet the description still notes 'short cards' vs get_item. All 19 parameters are documented in the schema, and the behavioral defaults are covered, so an agent has everything needed.

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%, so the baseline is 3. The description adds genuine value beyond the schema by explaining the AND-combination rule and the interaction between include_finished and the finished category values, which the schema does not state.

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 ('Find items') and explicitly differentiates itself from get_item by noting it returns 'short cards' while get_item gives 'the full story'. The scope is somewhat generic but the sibling routing makes the intent unambiguous.

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 clear operative context: filters combine with AND, finished work is excluded by default unless include_finished is true or a finished category is requested. Routes to get_item for full detail. Does not contrast with my_work or run_view, so it stops short of full when/when-not 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?

Annotations already declare it is a non-read-only, idempotent, non-destructive mutation. The description adds real value beyond that: the admin-only auth requirement and the fact that the mutation is reversible via shipped: false, neither of which is captured by the 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?

A single tight sentence that front-loads the primary action, then the inverse case, then the permission constraint. Every clause carries information; 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?

With 100% schema coverage, an output schema, and annotations carrying the safety profile, the description fills its remaining obligations (auth requirement, inverse operation). It is essentially complete, though it could note side effects on release contents.

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%, so the baseline is 3, but the description adds meaning the schema omits – it explains that setting 'shipped' to false un-ships the release, whereas the schema only says 'Defaults to true'. It adds no detail for project/release keys, which the schema already covers.

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 ('Marks a release shipped') and clarifies both the forward and inverse operation. It is clearly distinct from the closest sibling create_release, which creates rather than transitions state, though it never names that sibling explicitly.

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?

Covers both directions of the operation (ship and un-ship via shipped: false) and adds an 'Admins only' precondition, which is genuinely useful context. However, it gives no explicit when-to-use-vs-alternatives guidance or mention of prerequisites/conflicts relative to create_release.

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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real behavioral context beyond them: only one timer exists across all workspaces and starting a new one terminates the previous one, which is a meaningful side effect on other resources. It does not mention auth or rate limits, but for a timer tool that is acceptable.

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 short sentences, front-loaded with the action and immediately followed by the side effect. The closing 'stopped says which one ended' is somewhat redundant given an output schema exists, but it is brief and reinforces the uniqueness rule.

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?

With annotations, a full output schema, and 100% schema coverage, the description only needs to add behavioral nuance, which it does via the single-timer rule. Nothing an agent needs to call it correctly appears to be 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% with only two parameters, so the schema already carries key and note semantics. The phrase 'on an item' loosely maps to key, but the description adds no format or constraint detail beyond the schema's 'Like APP-123' example. Baseline 3 applies.

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 ('Starts your timer on an item') that clearly separates it from stop_timer, timesheet, and log_time. It does not, however, address the potentially confusable sibling start_work, leaving that distinction 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?

The description implies when to use it (when starting tracked time on an item) and discloses a precondition-like behavior, that any running timer is stopped first. It never names an alternative tool or states when not to use this one, so guidance is only implied.

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?

Adds substantial context beyond the annotations: it discloses conditional assignment, conditional column move, that the timer stops any other timer across all workspaces, and that it returns a git branch name. None of this is captured by readOnlyHint=false / destructiveHint=false, and nothing contradicts those hints.

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 front-loaded sentences with no filler; the compound action is stated first and the return value last. The parenthetical 'stopping any other, in any workspace — done says which' is dense but earns its place by flagging a cross-workspace side effect.

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 multi-effect mutation tool this covers the essential behavior, the cross-workspace timer side effect, and the meaningful return value, and an output schema exists to carry structured results. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so the schema already documents key, note, and timer (including the default). The description references the timer effect but adds no format or edge-case detail beyond the schema, so the baseline 3 applies.

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 composite action (assign, move to in-progress, start timer) on a named resource (an item), and the return value is called out. An agent can distinguish it from start_timer/stop_timer/finish_work without opening any 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?

Usage is implied by the described side effects, and the aside 'done says which' gestures at the finish_work counterpart. However, there is no explicit when-to-use or when-not-to-use guidance versus siblings like start_timer, which performs only the timer portion.

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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds meaningful context beyond these by clarifying that the timer is stopped globally, across any workspace, not just the current one. It does not contradict the 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 a single front-loaded sentence with no wasted words. It delivers the core action and scope immediately, which is ideal for a zero-parameter tool.

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 simple zero-parameter timer action, the description is complete: it states what happens and the cross-workspace scope. Annotations cover idempotency and safety, and an output schema exists, so return values and error behavior need not be explained here.

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 tool takes zero parameters, so the baseline is 4. The description correctly does not discuss parameters, and the schema requires no additional semantic explanation.

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 — 'Stops your running timer' — and adds a clear scope: 'wherever it is — in any of your workspaces.' This distinguishes it from siblings like start_timer and delete_time_entry, which operate on different resources.

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 when to use it: when you have a running timer. However, it does not explicitly compare it to alternatives such as log_time, delete_time_entry, or timesheet, nor does it state exclusions or prerequisites. Usage is implied but not spelled out.

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context: that results are grouped per day and per item, that totals are included, and that a currently running timer is reported. That is meaningful extra information beyond what the annotations provide.

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 tight sentence that front-loads the primary resource and scope, then layers the output shape and the downstream id usage without waste. Every clause earns its place.

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 read-only report tool, the description covers scope, defaults, result grouping, totals, the timer-state signal, and the practical link to edit_time_entry, while annotations cover safety and an output schema covers return structure. An agent has everything needed to select and call 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 100%, with both date parameters fully documented including accepted formats and defaults, so the schema carries the parameter burden. The description restates the two-day range and its default but adds no format or edge-case detail beyond the schema, which is the expected 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?

The description states a concrete resource and scope: the caller's logged time between two days, broken out per day and per item, with totals and entry ids. It is clearly a reporting/read tool and even names edit_time_entry as the downstream consumer of the returned ids, though it does not explicitly distinguish itself from a potentially similar sibling such as my_work.

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?

Usage is implied rather than stated: the default range (this week so far) and the mention that entry ids can be fed to edit_time_entry hint at when the tool fits. There is no explicit when-to-use/when-not-to-use guidance or comparison against alternatives like my_work or log_time.

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?

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true), so the bar is lower, and the description still adds real behavior: replace-vs-adjust semantics per field family, and 'Every name is checked before anything is written', which discloses a validate-then-write ordering. It does not describe error handling when a name fails validation or how the 'clear' mutation interacts with concurrent edits.

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?

Five short clauses, front-loaded with the core contract ('Changes any fields... leave out what should stay') and then the field-family rules. No sentence is redundant with the name or title, and 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?

For a 19-parameter mutation tool with an output schema and full annotations, the description covers the essentials: partial-update semantics, replace-vs-adjust, move semantics, clearing, and pre-write validation. The remaining gap is guidance on conflicting or redundant parameter combinations, which the schema does not resolve either.

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%, so the baseline is 3, and the schema already documents most individual fields. The description adds semantics the schema does not: that omitted fields are untouched (partial-update behavior) and that status/category cause a move rather than a plain value change. It does not clarify whether status and category, or labels and add_labels, can be combined.

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 ('Changes any fields of one item') and pins down scope with 'leave out what should stay'. It also orients the agent relative to siblings: 'status or category moves it' explains that moves happen through this tool's fields, and 'Answers the item as get_item does' links the response shape to get_item.

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 clear operating context: omit a field to leave it unchanged, and choose labels/assignees to replace the set versus add_*/remove_* to adjust it. It does not state any when-not conditions or mutually exclusive combinations, so it stops short of full routing 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?

Annotations already declare readOnly=false, idempotent=true, destructive=false and openWorld=false, so the mutation/safety profile is covered. The description adds nothing beyond that — it does not state that unspecified fields are left unchanged, nor any auth or side-effect details — so it neither contradicts nor enriches the 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?

A single front-loaded sentence with no filler; each listed operation earns its place by telling the agent which fields are in play.

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?

With an output schema present, a fully documented 5-parameter input, and rich annotations, the description is adequate; the only mild gap is that partial-update semantics (omitting a field leaves it untouched) are left to inference.

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 100% and every parameter carries its own description, so the baseline is 3. The one sentence maps loosely onto title/remind_at/completed/clear_reminder, but adds no format, default, or interaction detail beyond what the schema already says.

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?

Specific verbs (renames, reschedules, ticks off, un-ticks) applied to a single resource ('one to-do'), which cleanly separates it from add_todo, delete_todo, and list_todos without opening a 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 enumerated operations imply the tool is for modifying an existing to-do, but there is no explicit when-to-use statement, no prerequisite mention (e.g. obtaining todo_id via list_todos), and no named alternative such as update_item vs add_todo.

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