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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: 'The scope line is what routing is judged against', and advises how to phrase the scope. It does not, however, mention side effects, reversibility, permissions, or any other behavioral aspects. The routing detail is valuable but the overall disclosure is incomplete for a mutation 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?

The description is two concise sentences that front-load the purpose and then deliver actionable guidance. Every sentence earns its place; there is no fluff or redundancy. It is appropriately sized and easy to scan.

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 (3 required parameters, full schema coverage, no output schema), the description covers the essential aspects: what the tool does, the distinction between project and area, and the critical routing behavior. It does not describe return values or error conditions, but these are less critical without an output schema. The description is nearly complete for the tool's complexity.

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 each parameter having a description. The description adds meaningful semantics beyond the schema, notably the guidance on scope ('write it as a plain description of what belongs here rather than a title') and the clarification of project vs. area. This enhances the agent's understanding beyond the raw parameter definitions.

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 verb 'Add' and the resource 'project or an area', and explicitly distinguishes between the two ('A project finishes; an area is ongoing'). It explains the purpose ('so captured items have somewhere to go') and even clarifies how the scope parameter is used for routing. This fully clarifies the tool's function without ambiguity.

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 the tool is used after capturing items ('so captured items have somewhere to go') and provides guidance on choosing between project and area. However, it does not explicitly contrast this tool with its siblings (capture, shortlist, mark_done) or state when not to use it. The usage context is implied but not fully 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?

With no annotations, the description carries the behavioral burden. It discloses that capture auto-classifies, auto-assigns projects, checks for existing duplicates, and files the item, and that text is stored verbatim and never rewritten. It stops short of explaining what happens on duplicate detection or where the item is filed, but these are not essential for invocation.

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 definition is well organized: purpose, batching rule, autonomous behavior, and agent instructions in four sentences. It is efficient, though 'call it once per distinct item' and 'paste a transcript one item at a time' are slightly 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 two-string-parameter tool with no annotations or output schema, the description is unusually complete: it specifies what to send, how often, what the tool decides, and what the agent should not do. The only minor gap is the absence of any return-value or confirmation behavior, but that is not needed to invoke the tool 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 coverage is 100% and already documents text and source. The description adds a useful constraint not in the schema: the text parameter must carry one distinct item at a time, not a batch. The verbatim/stored-exactly point repeats the schema, but the batching rule is genuine added meaning.

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 uses a specific verb and resource ('Save something the user wants kept: a note, a link, an email...') and clarifies that capture is the catch-all intake tool. It also distinguishes itself from siblings by stating it decides project, attention, and duplicates itself, so an agent won't confuse it with add_project or mark_done.

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 concrete usage rules: call once per distinct item, paste a transcript one item at a time, and do not classify or ask which project. It does not explicitly name sibling tools as alternatives, but the 'decides for itself' statement effectively routes the agent away from add_project and mark_done.

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?

The description explicitly states 'Nothing is deleted,' which is a valuable behavioral disclosure beyond the schema. It clarifies that the operation is non-destructive, which is important for an agent deciding whether to call it.

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 waste. The core action and the key non-destructive behavior are front-loaded.

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 one-parameter tool with no output schema, the description is complete. It explains the effect and the non-destructive nature. It could mention what happens to the item after marking, but that is not essential for calling the 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 description coverage is 100%, so the schema already documents the 'id' parameter. The description adds no additional parameter semantics beyond what the schema provides, which is acceptable given full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Mark') and resource ('an item'), and clarifies the effect ('finished so it leaves the shortlist'). It distinguishes itself from siblings like capture and add_project by focusing on the shortlist lifecycle.

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 an item should be finished and removed from the shortlist. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for a simple 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the nature of the output (a ranked list of open/quiet items) and the absence of arguments. It implies a read-only operation without stating it explicitly, but for a summary tool that's acceptable. It does not mention any side effects or prerequisites, which is appropriate given the simplicity. A 5 would involve explicit statement of no side effects or auth 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?

The description is two sentences long, with the first sentence defining the tool's functionality and the second providing usage guidance. The 'Takes no arguments' sentence is redundant but does not detract. Information is front-loaded: purpose first, usage second. No word 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?

For a tool with no parameters and no output schema, the description is complete. It explains what the tool returns (ranked list of open items and quiet projects), when to use it, and that it takes no arguments. The agent has everything needed to call it correctly. There are no missing pieces given the tool's simplicity.

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 has zero parameters, and the schema shows an empty object. The baseline for zero parameters is 4, as the schema fully covers parameter semantics. The description redundantly states 'Takes no arguments,' which adds no new meaning beyond what the empty schema already conveys, but it doesn't hurt. Thus, the score matches the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states what the tool returns: 'The few things that matter today, ranked out of everything still open, with any projects that have gone quiet.' This is a specific, unambiguous output that clearly distinguishes it from siblings like capture, add_project, and mark_done, which perform different actions (capturing, adding, marking done).

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 provides explicit usage triggers: 'Call it when the user asks what they should be doing, what is outstanding, or at the start of a working session.' This clearly tells the agent when to use the tool. It doesn't explicitly exclude alternatives, but the siblings are semantically distinct (they are data-modifying actions), so the guidance is sufficient. A 5 would require explicit 'when not to use' or contrast with siblings, which is missing.

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