GTD Brain

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

Annotations declare destructiveHint=true and idempotentHint=true; the description adds the critical nuance that 'destructive' here means hidden from the board, that restore_card reverses it, and that there is no delete — materially changing how an agent should treat the side effect. It also instructs informing the user and states the return value.

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-loaded with the use condition, and each subsequent clause carries routing or behavioral value (alternatives, reversibility, bulk-exclusion, return). It is dense but slightly overpacked with prohibitions that could be trimmed without losing meaning.

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?

No output schema exists, but the description states the return ('Returns the archived card'). Combined with explicit exclusions, preconditions, and reversibility, an agent has everything needed to call this 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?

One parameter with 100% schema description coverage ('The card id to archive'), so the schema carries the semantics. The description adds no format or sourcing detail for cardId beyond what the schema already says; baseline 3 is appropriate.

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 (archive a card) and immediately distinguishes it from the sibling behaviors an agent might confuse it with — move_card, update_card, restore_card, and deletion. An agent can select this tool 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?

Gives explicit triggering language ('done, finished, or no longer needed'), a pre-check (list_columns for a Done column), the alternative to use in that case (move_card), and three explicit when-not conditions. This is a full routing decision tree, not mere 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 (not read-only, not destructive, not idempotent), so the description's job is to add beyond that. It does: the 'no column lookup / capture first, clarify later' behavior and the explicit 'Returns the created card' statement tell the agent what happens on success, which annotations do not. It stops short of documenting duplicate handling or failure modes, so not quite a 5.

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 front-loaded with the positive trigger before the negative exclusions, and every sentence carries routing information. It is somewhat long with three example utterances and two prohibition clauses, but nothing is clearly 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?

No output schema exists, yet the description states the return value, and for a 3-param create tool with full schema coverage the description supplies everything needed: trigger conditions, exclusions, alternative routing, and the success response.

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 title, notes, and context, including the retry-on-error behavior for unknown context ids. The description adds no parameter-level guidance beyond what the schema states, 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?

The description states a specific action (capture straight to Inbox in one step) on a specific resource (a card), and explicitly distinguishes itself from create_card and from card-completion flows. An agent can tell it apart from every relevant sibling 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?

It gives explicit when-to-use triggers with example utterances, names the alternative (create_card) and the exact condition that selects it (user names a destination list or card kind), and rules out mutation/completion cases with pointers to search_cards. This is about as complete as routing guidance gets.

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 this is a non-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds real behavioral context beyond that: columnId must be resolved via list_columns first, the kind value is constrained by destination column, and it states what is returned. It does not discuss failure modes or duplicate creation, keeping it short of a 5.

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-loaded with the triggering condition and dense with actionable content — nearly every clause rules an intent in or out. The middle section is one long run-on chain of cases, which is heavier than ideal but each clause carries routing value, so it is not padding.

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 an 8-parameter write tool with no output schema, the description covers prerequisites (columnId from list_columns, projectId from list_projects), value constraints, alternatives, and the return ('the created card'). It omits board position/ordering behavior, which is a minor gap rather than a blocking one.

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 goes beyond the schema by stating the cross-parameter rule the schema only implies per-field: 'kind action only in Next Actions, project only in Projects, card anywhere else', plus the projectId/lookup requirement. This is genuine added meaning, though per-field examples largely duplicate 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?

States a specific verb and resource (create a card) and then enumerates exactly which user intents map to it — next action, project step, project, waiting-for, Someday/Maybe, reference, custom column. It explicitly distinguishes itself from siblings by naming capture, search_cards, move_card, update_card and archive_card as the wrong tools in specific cases.

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 when-to-use triggers ('use this when the user says where a card belongs or what it is') and two explicit when-NOT-to-use rules with named alternatives: bare 'add/remind me/note' with no list → capture; a card already on the board → search_cards + move_card/update_card, with a stated reason (archive_card loses history).

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 discloses that the id is derived from the label and must not already exist, and that color is optional and auto-picked. Since the annotations are only sparse boolean flags, this text carries the behavioral burden well, though it does not mention response or failure 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?

Three focused sentences that front-load purpose, then state constraints, then give exclusions. Every sentence earns its place with 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?

For a two-parameter creation tool with no output schema, the description covers the core purpose, constraints, and alternative tools. It is complete enough for an agent to select and 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%, so the baseline is 3. The description adds value by clarifying label semantics with examples and explaining the derived-id and auto-color behavior beyond what the schema provides.

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 ('create' a GTD context) and defines what a context is with concrete examples like '@boat', 'errands', 'deep work'. It clearly differentiates from sibling tools like update_context, delete_context, and create_card.

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 says when to use it ('when the user wants a new GTD context') and when not to use it: if a matching context already exists, check list_contexts first; for tagging a card, use update_card with the existing id. This is strong 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 destructiveHint=true and idempotentHint=true, but the description adds critical behavior: every card tagged with the context, including archived cards, has its context cleared, and that confirmation is needed before calling. This goes beyond the annotations and materially informs the agent about consequences.

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

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

Two sentences deliver the trigger condition, a critical behavioral warning, an explicit exclusion, and the alternative tool. Every clause earns its place, and key guidance is 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 one-parameter destructive tool with annotations covering idempotency and destructiveness, and no output schema, the description covers all essential aspects: what it deletes, what it affects (archived included), when to use it, and when not to. No missing information that would prevent correct invocation.

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 contextId is already well-documented in the schema ('The context id to delete, from list_contexts'). The description does not add further parameter semantics but also does not need to 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 action (removing a context from the user's set) and clearly differentiates it from the sibling tool update_card. The distinction from removing a context from a single card is explicit, leaving no ambiguity about what this tool does.

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 an explicit condition for use ('when the user explicitly wants a context removed from their set') and an explicit exclusion ('Do not use to take a context off one card') with a named alternative (update_card with an empty context). This is textbook usage 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 and non-destructive, so safety is covered; the description adds genuinely new behavioral detail about the payload — notes, context, who it is waiting on and since when, and a chronological history of create/move/edit/review/archive/restore events ordered oldest first. It stops short of noting limits (pagination, history truncation), so not a full 5.

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 but well-ordered sentence that front-loads the precondition, then the payload, then the exclusion. It is longer than minimal but each clause carries routing or payload information an agent needs.

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 no output schema, the description usefully enumerates what the call returns (details plus an ordered history), which is the main thing an agent would otherwise lack. Minor gaps remain around history size/ordering guarantees and whether archived cards are returned, but the definition is largely self-sufficient for a one-parameter read 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% with a single cardId parameter whose schema description matches the text ('from a list, search, or earlier result'). The description adds no format, validation, or edge-case semantics 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 precise verb+resource ('get_card' returns a card's full details and history) and explicitly contrasts itself with the sibling search_cards. An agent can distinguish it from list_cards, search_cards, and update_card 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?

Gives an explicit precondition ('when you already have a card id ... from a list, a search, or an earlier result') and a negative rule ('Do not use to find a card by text — use search_cards'), naming the alternative tool directly. Both when-to-use and when-not-to-use are covered.

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, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond them: filters combine (AND semantics) and archived cards appear only when includeArchived is set. It omits return ordering/pagination, which keeps it short of a 5.

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 tight sentences, front-loaded with the primary use case, then the filter-combination rule, then the routing/exclusion guidance. No filler and nothing repeated from the schema.

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, five-optional-param list tool with no output schema, the description covers scope, filter interaction, archival behavior, and sibling routing. An agent has everything needed to invoke it correctly; return-format detail is not required for a plain-data list.

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 goes beyond it by stating that filters combine and that includeArchived is the gate for archived cards — a cross-parameter interaction the schema does not express. It adds real meaning rather than restating field docs.

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

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

Opens with a specific verb+resource+intent ('cards as plain data to reason over') and enumerates the actual result shapes (one column, one kind, one context, a project's actions). It explicitly names the siblings it is not (list_next_actions, list_projects, list_waiting_for, search_cards), so an agent can disambiguate 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?

Gives positive selection criteria ('when you need cards as plain data'), routing rules for the three main lists, and an explicit negative ('Do not use to find a card by words in its title — use search_cards'). This is a full when/when-not/alternative triad.

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 provide the safety profile (readOnlyHint, idempotentHint, destructiveHint), so the bar is lower. The description adds useful behavioral context beyond annotations: the returned cardCount excludes archived cards, and custom columns are included alongside the standard set. This clarifies the scoping of results.

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 moderately long but every sentence earns its place: primary use case, return shape, and exclusionary guidance. It is front-loaded with the most critical usage information, though the phrase 'the number of cards on the board in it' is slightly redundant after 'cardCount'.

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 zero-parameter read-only tool, this description is complete: it explains when to call it, what it returns (including field names), the archived-card exclusion, and how it differs from sibling tools. 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?

The tool has zero parameters and an empty schema, so there are no parameter semantics to document. The baseline for 0-parameter tools is 4, and the description adequately covers return values instead.

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 purpose: list all columns with their metadata, and explicitly frames it as the go-to for obtaining column ids for create_card, move_card, or list_cards. It identifies the resource (columns) and distinguishes itself from list_cards by noting it carries no cards.

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 explicit when-to-use conditions: when you need a column id, when the user asks what lists a board has, or when counting cards per list. It also provides when-not-to-use guidance and explicitly points to list_cards or list tools as the alternative for actual card content.

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 tool read-only, idempotent, and non-destructive. The description adds value beyond that by disclosing the returned fields and the important constraint that context ids are user-defined and unknown ids are rejected. This is helpful context that the annotations do 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?

The description is concise and front-loaded with the primary use case. It packs purpose, return contents, and a critical constraint into two sentences with no wasted words or redundant restatements of the tool name.

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 no parameters and no output schema, the description fully covers what an agent needs: when to use the tool, what it returns, and the caveat about not guessing context ids. There is no meaningful missing context for this simple read-only operation.

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, so the description does not need to explain parameter semantics. It goes slightly beyond the empty schema by describing the returned fields, which is useful context for the caller. A baseline of 4 is appropriate for a zero-parameter tool.

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's purpose: retrieving the user's context ids and metadata. It specifies the resource (contexts), the returned fields (id, label, color, order), and its role as a prerequisite for several sibling tools, making it easy to distinguish from other list or context-management tools.

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 guidance: before passing a context to list_next_actions, list_cards, create_card, or update_card, or when the user asks which contexts they have. It does not explicitly state when not to use it or name alternatives, but for a simple read-only listing tool this is not a significant 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 readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds meaningful behavioral detail about what is returned (cards with context and project), the source (Next Actions column), and ordering (board order). 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?

Front-loaded with the when-to-use condition, followed by the behavior and exclusions. It is somewhat dense but every clause earns its place; no filler or repetition of schema details.

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 read-only list tool with one optional parameter and no output schema, the description is sufficient: it covers intended use, exclusions, output content, and ordering. It does not discuss pagination or empty states, but those are minor for this type of 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 description already provides rich detail about the context parameter, including examples, management via list_contexts/create_context, and recovery when an unknown id is given. The tool description adds the practical trigger for narrowing by context, going slightly beyond the schema's technical description.

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: 'Lists the Next Actions column (each card with context and project), in board order.' This clearly differentiates it from siblings like list_cards and search_cards, and the name reinforces the 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?

Explicitly states when to use: when the user asks what to do now, next actions, or to-do list, with optional GTD context narrowing. It also provides clear exclusions with named alternatives: list_projects, list_waiting_for, list_cards, and search_cards.

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, covering the safety profile. The description adds behavioral context by specifying that output is in 'board order' and clarifying the definition of a project. It does not contradict annotations. While it doesn't describe output fields, the annotation coverage lowers the bar, and the added ordering context is 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?

The description is a concise two-sentence block that front-loads the primary usage trigger and then provides the tool's behavior and exclusions. Every sentence earns its place with no redundancy or 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?

Given there are no parameters and no output schema, the description covers the essential facts: when to use it, what it lists, and how it defines a project. It doesn't describe the exact output shape, but for a straightforward list tool with strong annotations, this is sufficient for an agent 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?

The tool has zero parameters, so the baseline is 4 per the rubric. The description correctly leaves parameter semantics untouched since there are none to explain. No additional value is needed here.

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's purpose: it lists the Projects column in board order, defines what counts as a project ('any outcome that needs more than one step'), and differentiates from sibling tools by naming specific alternatives (list_next_actions, create_card). This makes the tool's function 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?

The description provides explicit usage triggers ('when the user asks about their projects, their open outcomes, or which projects have no next action yet') and explicit exclusions ('Do not use for single tasks (list_next_actions) or to add a project (create_card)'). It names the alternatives directly, leaving no ambiguity about when to select this 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 readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral context beyond annotations: output is in board order, includes delegation recipient and since when, and is scoped to the Waiting For column. No contradiction with 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?

Three concise sentences: trigger conditions, output format, and exclusion. Each sentence adds distinct value, front-loads the usage guidance, and is compact with no verbosity.

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?

Complete for a simple read-only listing tool with no parameters and no output schema. The description covers trigger conditions, behavior, output details, and alternative selection, leaving no ambiguity for an agent to invoke 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?

The tool has zero parameters, so schema coverage is trivially 100%, and the baseline for zero-parameter tools is 4. The description adds no parameter-specific info because none exist, which is appropriate.

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 ('Lists') and resource ('Waiting For column') and details the output (each card with who it is delegated to and since when). It also explicitly differentiates from sibling list_next_actions by saying 'Do not use for the user's own tasks (list_next_actions).'

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 trigger conditions: 'when the user asks who they are waiting on, what they have delegated, or what to follow up on with other people.' It also gives a clear when-not and names the alternative: 'Do not use for the user's own tasks (list_next_actions).'

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 declare idempotentHint=true and destructiveHint=false, so safety is covered. The description adds the key behavioral fact that the card 'stays in its list and counts as reviewed now,' which the annotations do not express. It doesn't cover auth or rate limits, but the main state effect is 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?

Two sentences, front-loaded with the primary use case, followed by the exclusion and alternatives. Every clause earns its place with 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?

Given the simple one-parameter tool, idempotent/non-destructive annotations, and no output schema, the description is complete. It covers purpose, routing, and the state outcome, and the 'Returns the card' note handles the return value even though no output schema exists.

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 single cardId parameter is already documented in the schema. The description adds no syntax or meaning beyond what the schema provides, so the baseline of 3 is correct.

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 ('mark... reviewed') and resource ('card'), and the description explicitly scopes it to a weekly review with 'keep' intent. It distinguishes itself from sibling mutation tools by naming move_card, update_card, and archive_card as the wrong choices for change scenarios.

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?

Explicit when-to-use ('during a weekly review when the user keeps a card as it is') and when-not-to-use ('Do not use when the card should change'), with the correct alternatives named. Nothing is left to inference about routing.

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 non-readonly, non-destructive, idempotent, so the safety bar is met; the description goes well beyond by disclosing the side effect that the card's kind follows the destination (Next Actions → action, Projects → project, etc.), the archived-card rejection, and that re-filing is one move rather than create+archive.

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 core action and the key routing rule ('move it to done' → move_card), but the dense em-dash-embedded clauses make it long and slightly hard to scan. Every sentence carries information, so nothing is truly 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?

No output schema exists, so 'Returns the moved card' is a valuable addition, and the description covers error handling (archived rejection), kind side effects, the correct alternative tools, and how optional clarifying fields combine. Complete for a 7-param 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%, so baseline is 3. The description adds cross-parameter semantics the schema does not: context/project/who/since should be set in the same call, and who/since apply specifically when landing in Waiting For. It does not explain toIndex or the empty-string clearing behavior, so it isn't a full 5.

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 (moving a card between columns) and immediately distinguishes it from siblings: 'Do not use to only edit a card's text or tags — use update_card', 'never archive_card', 'use restore_card'. An agent can select it correctly 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?

Explicit when-to-use (clarifying Inbox, reordering, moving to a Done-style column) and when-not (text/tag edits → update_card; archived → restore_card). It even decodes the ambiguous natural-language phrase 'move it to done' and routes it to the right column lookup via list_columns.

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 indicate idempotentHint=true and destructiveHint=false, so the description complements by explaining the default behavior (returns to original column or Inbox), the optional toColumnId, and the rejection of move_card on archived cards. It clearly describes the operation's effect and edge cases, going beyond 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 concise and front-loaded with the purpose, then essential steps, alternatives, and edge cases. Every sentence adds value, no fluff.

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 clear annotations, the description covers all necessary aspects: when to use, how to find input, default behavior, optional parameter, and a critical warning about move_card. Comprehensive and sufficient for an agent to call 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%, so parameters are already documented. The description adds value by explaining the default for toColumnId and the source of cardId from search_cards, but the schema already covers the basics. Hence, a 3 is appropriate.

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 specific verb and resource: 'restore' an 'archived card' to the board. It includes trigger phrases and clearly distinguishes from move_card by stating it is rejected for archived cards.

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 says when to use (archived card back on board), how to find the card (search_cards with includeArchived=true), and warns against using move_card on archived cards. Mentions alternative tools like search_cards and move_card.

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 read-only, idempotent, non-destructive. The description adds valuable behavioral details: case-insensitive matching, every word required, any order, and the includeArchived flag. It exceeds what annotations alone convey.

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

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

The description is a single paragraph but packed with necessary information. It could be slightly trimmed, but every sentence earns its place, and the usage guidance is 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 read-only search tool with no output schema, the description covers the essential aspects: matching rules, archived handling, and exclusions. Missing return format is minor and not required for successful invocation.

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 descriptions cover both parameters, but the description adds crucial semantics: the matching rule (all words, any order) and the example clarifying query behavior. This goes beyond the schema's basic 'words to look for'.

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 specific verb and resource: searching cards by words in title/notes, with clear differentiation from list tools and get_card. The description makes it obvious that this is a search operation, not a list or fetch.

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 when to use (user refers by words, need id/details, or checks existence) and when not to (listing a whole column, pointing to list_cards). The example and exclusion are unambiguous.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds genuine behavioral context beyond them: patch semantics ('Only the fields passed change'), the empty-string-clears convention, and the return value ('Returns the updated card'). It does not cover auth requirements or what happens to unspecified fields beyond the partial-update note.

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 front-loaded sentences: capability, patch/clear semantics, exclusions, return value. Every sentence carries distinct information with no padding or repetition.

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 7-parameter partial-update tool with no output schema, the description covers mutation scope, clearing behavior, sibling routing, and the return value. 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 every parameter including the empty-string clearing behavior for context and projectId. The description restates the fields and generalizes the clear convention, adding only marginal value over the structured data. Baseline 3 is appropriate.

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+resource and enumerates exactly what can be changed (title, notes, context, project link, who/since), which maps cleanly onto the schema. It explicitly distinguishes itself from move_card and archive_card by name, so an agent can route 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?

It gives explicit when-to-use triggers (retitle, edit notes, set/clear context, link/unlink project, change delegation), explicit when-not-to-use conditions (column placement, reordering, finishing/removing), and names the correct alternative for each exclusion.

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 annotations declare non-destructive, idempotent behavior, so the description needn't repeat those. The description adds valuable behavioral constraints: only user-added columns can be renamed, system columns keep their names, and no plain column can move ahead of the Inbox. It does not mention permissions or rate limits, but the constraint detail is strong. Slightly less than 5 because it doesn't mention partial update behavior or what happens if both label and toIndex are 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?

Three sentences with zero waste. Front-loads the purpose, then constraints, then the alternative tool. No repetition or 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?

Given annotations cover safety and idempotency, schema covers parameters fully, and no output schema exists, the description provides sufficient context: purpose, constraints, alternative tool, and return ('Returns the column'). Missing only a note on what happens if both label and toIndex are provided (though schema implies both can be used), but overall complete for an update 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%, so the schema already documents all three parameters with examples and edge cases (out-of-range values go to end). The description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is correct when 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?

The description states a precise verb+resource ('rename one of their own columns or put a column in a different position') and gives concrete examples. It distinguishes itself from move_card explicitly and from other column operations.

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?

Explicit when-to-use ('when the user wants to rename... or move a column') and when-not-to-use ('Do not use to move cards — use move_card'). It also names the alternative tool and states the constraints on which columns can be renamed and the Inbox restriction.

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 (not read-only, not destructive, idempotent). The description adds meaningful behavioral context: the id never changes, so cards keep their assignment. This explains an important invariant beyond what 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?

Two sentences with no wasted words. The primary use case is front-loaded, followed by a key behavioral invariant and a clear pointer to the sibling tool. 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?

For a low-complexity tool with only three parameters, full schema coverage, and helpful annotations, the description is complete. It covers purpose, usage boundaries, and an important side effect, and no output schema is expected for this update operation.

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 each parameter already has a clear description. The tool description adds only the label/color mapping implicitly through 'rename or recolor,' which is mild added value but not a significant enhancement over 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 states a specific verb and resource: 'rename or recolor one of their contexts.' It clearly distinguishes itself from update_card, which changes a card's context assignment rather than the context's own label/color.

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 explicitly says when to use the tool ('when the user wants to rename or recolor one of their contexts') and gives an explicit exclusion: 'Do not use to change which context a card carries — use update_card.' This leaves no ambiguity about when this tool is appropriate.

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