Cherry Notes

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

Annotations already establish idempotency and non-read-only/non-destructive behavior. The description adds workflow-critical context beyond annotations: this is a mandatory precondition for other work and the agent must present the display field verbatim to the user. It stops short of describing the exact server-side effect of claiming items, but that is largely covered by 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 compact and imperative, with the most important workflow constraint front-loaded. It earns most of its sentences, though 'Requires idempotency_key' and the item_numbers/pick_all instruction duplicate schema information rather than adding new content.

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

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

For a tool with an output schema and full parameter documentation, the description covers everything needed to call it correctly: workflow position, required key, selection modes, and the mandatory user-facing display of the output. No critical invocation detail 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 each parameter has a rich description, so the baseline is 3. The description adds a useful example ('[3] for item 3') and highlights pick_all as an alternative, but it mostly restates what the schema already conveys about item_numbers, item_ids, and pick_all.

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 opens with a specific verb and resource ('Claims items for work') and immediately anchors the tool in the workflow ('STEP 1 — ALWAYS pick before doing any work'). This makes it unmistakable relative to siblings like cherry_unpick, complete_items, and get_items, even without naming them.

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 explicitly prescribed: 'ALWAYS pick before doing any work' and 'NEVER do work without calling this first.' It also gives concrete selection guidance (item_numbers from display, or pick_all=true) and notes the required idempotency_key, leaving no ambiguity about when and how to call it.

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 convey idempotentHint=true and destructiveHint=false. The description adds beyond that: it clarifies the action is a release (non-destructive), requires an idempotency_key, and notes that item_texts are 'Display only' and 'Ignored by the server.' It also instructs the agent to show the display field verbatim in a code block, which is behavioral guidance not present in annotations. No contradiction exists between description and 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 compact—five short sentences with no filler. The purpose is front-loaded, followed by usage, then a specific display instruction. It avoids redundant detail already in the schema. It earns a 4 rather than a 5 because it slightly repeats the idempotency requirement that is also in the schema and could be tightened, but overall it is well-structured and efficient.

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 mutation tool with an output schema and annotations covering idempotency and non-destructiveness, the description covers purpose, usage context, required parameters, and a special output instruction. It does not explicitly mention the alternative item_ids parameter, but that is already fully described in the schema. The description is complete enough for an agent to invoke correctly without needing to infer missing details.

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 parameters are already documented in the schema. The description adds minimal value: it repeats that item_numbers are required and that idempotency_key is needed, but it does not explain item_ids or item_texts beyond what the schema already states. The only extra is the instruction to show the display field, which pertains to output rather than parameters. Per the rubric, with high coverage the baseline is 3, and the description does not meaningfully elevate 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 clearly states a specific verb ('Releases') and a specific resource ('picked items back to todo'). It also gives a concrete use case: 'Use if you picked the wrong item or need to release work.' This distinguishes it from siblings like cherry_pick (which does the opposite) and complete_items (which marks done), so an agent can select it correctly without inspecting schemas.

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 explicitly says when to use it ('if you picked the wrong item or need to release work') and lists prerequisites ('Requires idempotency_key') and required input ('Pass item_numbers of the picked items'). It does not name alternatives or exclusions, but the context is clear and the sibling list includes cherry_pick, making the contrast obvious. This earns a 4 rather than a 5 because it stops short of explicitly saying 'do not use for X.'

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 readOnly=false, idempotentHint=true, and destructiveHint=false. The description adds important behavioral context beyond that: the user-confirmation requirement and the instruction to show the `display` field verbatim in a code block. These are not visible in the annotations or schema and meaningfully shape how the agent uses the tool.

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 short, purposeful sentences with the main action first, followed by the key precondition, required parameter, and display instruction. Every sentence earns its place and there is no filler or redundancy.

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 description, combined with full schema coverage and annotations, gives the agent everything needed to call the tool correctly: what it does, when it is allowed (after confirmation), what to pass, and what to show the user. The output schema handles return-value details, so no further explanation is required.

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 emphasizes item_numbers and idempotency_key, but this largely repeats what the required fields already communicate. It does not add meaningful parameter semantics beyond the schema's already clear 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 description opens with a specific verb and resource: 'Marks picked items as done.' This clearly differentiates the tool from siblings like get_items (listing), cherry_pick/cherry_unpick (selecting/unselecting), and project-level tools. The phrase 'picked items' ties it to a prior get_items workflow.

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

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

The description gives an explicit precondition: ask for user confirmation before calling and only call after the user confirms the work is done. It also directs the agent to pass item_numbers and require idempotency_key. It does not explicitly name alternatives or exclusion cases, but the confirmation rule is clear and actionable.

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 confirm readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds important operational behavior: pagination via has_more/cursor, hiding cursor fields from the user, and displaying the `display` field verbatim in a code block. This is meaningful context beyond 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?

Front-loads the purpose, then moves to actionable rules in short imperative sentences. Every sentence earns its place by covering either purpose, sequencing, output handling, or pagination, with no redundant restatement of the name or title.

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 the description need not explain return values; it appropriately focuses on usage, pagination, and user-facing presentation. Given the tool's complexity and available schema, the description gives everything an agent needs to call and handle 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% for the single cursor parameter, so the schema already documents its meaning. The description references calling again with cursor for pagination but adds no new syntax or semantic detail beyond what the schema provides, matching the baseline of 3.

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: 'Returns the current items in the selected project,' and clarifies that items are tasks. It differentiates from siblings by naming cherry_pick, cherry_unpick, and complete_items, so an agent can distinguish it from other tools without inspecting schemas.

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?

Provides explicit ordering rules ('ALWAYS call cherry_pick before doing any work on items — NEVER do work without picking first') and a confirmation requirement before complete_items. Also states how to handle pagination and user-facing output, leaving little to inference.

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 and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it explains the pagination contract (has_more and cursor usage), specifies that the result should be presented via the `display` field, and clarifies the intended scope (all projects). These go beyond what annotations convey, though it doesn't describe the exact return structure (which the output schema handles).

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, tightly packed paragraph that leads with the primary purpose, then immediately gives usage exclusions, display instructions, and pagination guidance. Every sentence earns its place; there is no filler or redundancy.

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?

Given the tool's simplicity, the presence of an output schema, and the annotations covering safety, the description covers all essential aspects: what it does, when to use it, how to present results, and how to paginate. An agent has everything needed to invoke it correctly without further 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?

The sole parameter `cursor` is fully described in the schema (100% coverage), so the baseline is 3. The description reinforces pagination behavior ('If has_more is true, call again with cursor') but does not add new meaning about the parameter's format or semantics beyond the schema's own explanation. It's adequate but not additive.

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 clearly states the tool returns all of the user's projects, and explicitly differentiates it from get_items by explaining when it should not be used. It names a specific verb and resource, and the sibling distinction is explicit, so an agent can unambiguously select 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?

The description gives explicit when-to-use and when-not-to-use conditions, naming the alternative tool (get_items) and the exact user phrasing that triggers this tool vs. the sibling. It also provides specific instructions for presenting the result (show the `display` field verbatim in a code block) and pagination handling, leaving no ambiguity about invocation 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 cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds the key behavioral fact annotations cannot convey: this call mutates session/tool context for subsequent calls. It also gives an output-handling instruction (show `display` verbatim in a code block). It stops short of saying whether the selection persists, expires, or affects anything else.

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 dense sentences, front-loaded with the action and its effect, then the identifier rules, then the display instruction. No filler, though the trailing code-block formatting instruction is a slight aside from the core selection semantics.

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 described, and the description still covers the one output behavior that matters (echoing `display`). For a 3-param, 0-required selection tool, 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 coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: the preference ordering of project_number over project_id, the first-page-only constraint on numbering, and the fact that project_title is display-only and ignored by the server.

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 concrete verb+resource ('Selects a project') and immediately explains the consequence: get_items and cherry_pick will operate on the selected project. That downstream-effect framing distinguishes it clearly from list_projects and from the other siblings.

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?

Explicitly states the preferred path (project_number, 1-based index from list_projects) and the fallback (project_id for projects beyond the first page). It names when each identifier is invalid, so an agent can route correctly without guessing.

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