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

Annotations already declare non-read-only, non-destructive, non-idempotent behavior, so the safety profile is covered. The description adds the meaningful append semantics (items go to the end, preserving the given order), but says nothing about permissions, whether existing items are reordered, or the 30-item limit.

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; the append position and ordering constraint come first. The trailing '(one request each)' is slightly cryptic but not wasteful in length.

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, so the description need not explain returns, but for a mutation with 3 parameters it omits permissions, effect on existing checklist items, and the maxItems constraint. Adequate to call the tool, incomplete for predicting behavior.

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 67%: the task and workspace parameters are documented in the schema, but the items array itself has no description. The description's 'in the order given' is the only semantic hint for items, so it adds marginal value over the schema rather than compensating for the gap.

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 (add) and resource (checklist items) with a clear scope: appending to the end of a task's checklist in a given order. It is distinguishable from the sibling update_checklist_item, though the leading 'sol2flow:' token is a namespacing artifact rather than useful meaning.

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 when-to-use guidance and no explicit routing against update_checklist_item or create_task. The parenthetical '(one request each)' hints at an operational constraint but is ambiguous and never states prerequisites such as needing an existing task.

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 non-readOnly, non-idempotent, non-destructive; the description adds genuinely new side-effect information beyond them — that @-mentions trigger notifications and that text is rendered as Markdown/GFM. It does not restate the safety profile, which is the right 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?

A single dense sentence with the primary action front-loaded, followed by reply semantics and the mention syntax. Every clause carries information, though the mention-syntax fragment makes the sentence slightly packed.

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 non-idempotent write tool with full schema coverage and annotations covering safety, the description fills the gaps that matter: reply targeting, mention notification behavior, and content format. With no output schema, return-value details are not 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: reply_to must reference a *top-level* comment id (from get_task), and it documents the @[Name](user:<id>) mention syntax for user targeting that the schema does not express.

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 ('add a comment (Markdown) to a task') and covers both modes: top-level comment and reply. No sibling tool competes for this function, so the purpose is 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?

Explains both usage modes and where to source the reply id ('reply_to: its id from get_task'), giving the agent a concrete retrieval path. It does not spell out when not to use it (e.g. vs. update_task descriptions), but the context is clear.

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: the task leaves lists/search/counts but persists in timesheets and exports, re-archiving is a no-op (consistent with idempotentHint), and it is reversible via unarchive_task. The phrase "read-only until unarchive_task" is ambiguous — it describes the archived task's state, but an agent could misread it as the tool itself being read-only, which would clash with readOnlyHint=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?

Dense and front-loaded: purpose first, then visibility effects, then idempotency, then the reversibility and safety rationale. Sentences are terse and each carries a distinct fact, though the parenthetical about deleting is slightly editorial.

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 mutation with no output schema and annotations already declaring destructiveness and idempotency, the description covers everything an agent needs: what is affected, what is preserved, what happens on repeat calls, and how to reverse it. Nothing material 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%: the schema already explains that `task` accepts a key, URL, or id, and that `workspace` defaults to the configured or only workspace. The description adds nothing about parameter format or defaults, 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 ("archive a task") and immediately differentiates itself from the sibling unarchive_task, which it names. An agent can distinguish it from update_task, move_task, or a hypothetical delete 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 clear selection context: use archiving because deleting is not offered, and unarchive_task is the path back. It does not spell out explicit when-not conditions (e.g. use update_task if you only want to hide from one board), but the routing intent toward the reverse operation is 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows it's a non-destructive write that is not idempotent. The description adds valuable context: 'You become its board admin' and details on access modes (WORKSPACE vs RESTRICTED) and role assignment, which are not captured by annotations. It doesn't mention rate limits, but this is solid supplementary behavioral information.

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 concise sentences, front-loaded with the main action and followed by access details. No wasted words, though the access modes could be slightly more structured.

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 5-parameter mutation tool with no output schema, the description covers the core purpose, admin effect, access modes, and default behavior. It lacks explicit prerequisites (e.g., required permissions) and return value info, but given the annotations and schema, it is nearly complete.

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 60%, so the schema already documents 'lists', 'workspace', and 'default_role'. The description adds meaning for 'access' (enum values explained) and 'lists' (ordering), but does not cover 'name' constraints or fully document all parameters. Baseline 3 is appropriate given partial schema coverage and some added value.

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 ('create a board in a workspace'), notes optional lists with ordering, and differentiates from siblings like create_list. An agent can immediately tell this creates a board, not a task or list.

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?

Implies usage by describing access modes and default workspace resolution, but doesn't explicitly say when to use this vs alternatives like create_list (for adding lists to an existing board). No when-not-to-use guidance is provided.

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 and destructiveHint=false, so the safety profile is covered. The description earns credit by explaining *why* it is idempotent — an existing workspace- or board-level label is returned rather than duplicated — which is concrete behavior an agent cannot infer from the hints alone. It does not mention permission requirements.

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: purpose first, then the dedup behavior, then the color reference. Every sentence carries distinct information 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?

For a mutation tool with no output schema, the description should convey what comes back; it partially does by stating the existing label is returned in the dedup case. The main return shape for a fresh creation is still unstated, but the tool's behavior is otherwise well covered by annotations plus the color reference.

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 75% and the schema documents 'board' and 'workspace' but leaves 'color' vague ('Default gray'). The description compensates by enumerating the allowed color values plus the #RRGGBB format, which the schema does not provide. 'name' remains undocumented but is self-evident.

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 ('create') and resource ('a label on a board'), which cleanly separates it from siblings like list_labels, create_board, and create_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 description implies usage via the dedup rule ('If a label with that name exists ... that one is returned instead'), which tells the agent this is safe to call even when a label may already exist. However, it never states explicit when/when-not conditions or names an alternative tool for label management, so guidance is implied rather than declared.

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, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description adds two pieces of value beyond that: the append-at-end semantics (no positioning control) and the required editor/admin role, which is exactly the kind of auth context annotations don't 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?

Extremely compact and front-loaded, with the action stated first. The 'sol2flow:' vendor prefix is the only wasted token; otherwise every word 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 simple 3-parameter mutation with no nested objects and full annotation coverage, the description supplies the essentials: what is created, where it lands, and who may do it. Missing details (duplicate-name behavior, response shape) are minor since annotations carry the safety profile and 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 description coverage is 67%: board and workspace are documented in the schema, and 'name' is self-evident (max 120 chars). The description adds only the gloss that the list is a 'column', which mildly clarifies the 'name' parameter but does not add format or constraint detail. 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 gives a specific verb and resource ('add a list (column)') and even disambiguates the term 'list' as 'column', plus the placement ('at the end of a board'). That is enough to separate it from create_board and create_task, though it never names those siblings 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?

'Editors and board admins.' states who is permitted, which is a prerequisite, but there is no guidance on when to use this tool versus alternatives (e.g. create_board for a new board, or update/move tools for reordering). No when-not conditions are given.

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=false), so the description just needs to add context. It adds the meaningful auth constraint ("Editors and board admins") and default-target behavior (first list), though it omits side effects like notifications to assignees.

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 front-loaded sentence that states the core action first and packs defaults and formats efficiently. It is dense but no sentence is wasted, though the trailing permission clause reads as an afterthought.

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 reasonably covers purpose, defaults, formats, and permissions for a task-creation tool. It could note what is returned (e.g., the created task) but is otherwise complete enough 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?

Schema coverage is 73% and several parameters (title, labels, assignees) lack schema descriptions. The description compensates by explaining that labels are names, assignees accept "me"/usernames/names, and the description field is Markdown, adding real meaning beyond 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 opens with a specific verb+resource ("create a task on a board, in a list") and enumerates the settable fields, which cleanly distinguishes it from siblings like create_board, create_list, and create_label. 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 description states the access requirement ("Editors and board admins") and defaults (first list), which implies audience and context, but it gives no explicit when-to-use versus alternatives such as update_task or create_board. Usage context 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: tasks are returned 'in board order' and the result is capped at 300 tasks, a truncation limit the agent must know about. It stops short of describing pagination behavior at that cap.

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 efficient sentence that front-loads the resource and its contents. The 'sol2flow:' prefix is noise that earns no place, but otherwise there is no 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?

With no output schema, the description carries the burden of describing returns and does so by naming the included fields and the 300-task cap. It is nearly complete, missing only what happens beyond the cap and how nested list/task structure is ordered relative to include_tasks.

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 (board, workspace, include_tasks, response_format) are already documented in the schema. The description adds only marginal detail (task ordering) and does not clarify parameter behavior beyond what the schema provides, so the baseline of 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+resource ('a board with its lists and, in each list, its tasks') and enumerates the returned fields (key, title, due date, assignees, labels). It does not distinguish itself from siblings like list_boards, list_tasks, or get_task, but the operation itself is 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?

There is no when-to-use or when-not-to-use guidance, and no alternatives are named. An agent cannot tell from the text whether to reach for this versus list_boards or get_task; the intended usage is only implied by the name.

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 openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing the returned payload (including checklist item ids and latest comments), which matters because there is no output schema. It does not mention permissions or rate limits, but for a read tool this is a solid addition.

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, front-loaded with the core purpose ('one task in full') before the field list. Slightly run-on but every clause earns its place by describing what is returned.

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 carries the burden of telling the agent what comes back, and it does so comprehensively. The remaining gaps (pagination of comments, permission requirements) are minor for a single-record 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%, so the schema already documents task key/URL/id, the comments count with its default, the workspace default, and the response_format enum. The description adds no parameter-level meaning beyond that, so 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+resource ('one task in full') and enumerates the returned facets (assignees, labels, dates, estimate, description, checklist, links, comments). It is clearly the single-task counterpart to list_tasks, though it never names a sibling to contrast against.

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 task's full detail. There is no explicit when-to-use statement, no condition distinguishing it from list_tasks or search, and no prerequisites (e.g., that the task key/URL/id must resolve in the configured workspace).

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 openWorldHint=false, so the safety profile is covered. The description adds one useful behavioral detail beyond that — the timer may not exist ('if any') — but says nothing about permissions, empty-result shape, or whether it is scoped to the authenticated user.

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 the resource and the return payload. The 'sol2flow:' prefix is minor noise that earns nothing, but there is no padding otherwise.

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-required-parameter read tool with no output schema, the description conveys the payload (task and start time) and the empty case. Nothing critical is missing, though a hint about the authenticated-user scope would fully close it out.

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?

There is a single optional parameter with 100% schema description coverage, so the schema fully documents response_format including its default. The description adds no parameter meaning at all, which is the baseline 3 case 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?

The description states a specific resource ('your running timer') with a retrieval verb and clarifies the nullable case ('if any'), plus names the returned fields (task and start time). It implicitly distinguishes itself from start_timer/stop_timer/list_time_entries by scoping to the currently running timer, though it never names a 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?

Usage is only implied: an agent can infer this is the check used before start_timer or stop_timer, but the description never states when to call it or when to prefer list_time_entries instead. No exclusions or prerequisites are given.

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 this is a non-idempotent, non-destructive write. The description adds genuinely useful behavior beyond that: the link is relational and the other task automatically sees the inverse relation, which the agent could not derive from annotations or schema alone.

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, front-loaded with the operation and followed by the semantic detail that matters. Slightly terse and the inline backtick formatting is awkward, 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?

For a mutation tool with no output schema, the description covers the operation, its scope, and the relation semantics. It omits error behavior and whether re-linking is additive, but the essentials an agent needs to call it correctly are present.

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 75% and the `kind` enum has no schema-level description, so the description's explanation of each kind and its inverse counterpart is the only definition of what the values actually mean. It adds real meaning over the raw enum list.

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 ('link a task to another task') and scopes it to the same workspace. The sibling 'unlink_tasks' makes the inverse operation obvious, though the description never names or contrasts it 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?

There is no when-to-use guidance, no prerequisites, and no mention of the alternative (unlink_tasks) or when a link should be created. The kind enumeration hints at intent but does not tell the agent when to reach for 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=true and openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the response contents (keys, task counts, role), but says nothing about pagination behavior or result caps despite cursor/limit parameters.

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; the returned-field list is the highest-value content and comes immediately. The 'sol2flow:' prefix is wasted tokens but the rest is tight.

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

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

There is no output schema, so the description carries the burden of describing the return shape, and it does name the key returned fields. Combined with fully documented parameters and read-only annotations, an agent has enough to call it correctly; only pagination behavior is unaddressed.

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 every parameter (limit, query, cursor, archived, workspace, response_format) is already documented in the schema. The description adds no syntax or format detail beyond that, 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?

It states a concrete verb+resource (listing boards scoped to a workspace) and even names the returned fields (keys, task counts, your role). It doesn't explicitly contrast with siblings like get_board or search, but an agent can still tell this is the enumeration tool rather than a single-board 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?

There is no when-to-use guidance and no named alternatives, even though get_board, search and list_workspaces all overlap in this area. The only hint ('a workspace') is implied scope rather than a routing rule.

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 openWorldHint=false, so the safety profile is covered. The description adds useful context about which labels come back, but says nothing about ordering, pagination, or result limits.

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 the mode-dependent behavior front-loaded and no filler. The 'sol2flow: labels.' prefix is a slightly odd namespace stub but costs almost nothing.

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, loosely-parameterized list tool with full schema coverage and annotations carrying the safety profile, the description is sufficient; only return shape and pagination are unaddressed.

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 goes beyond the schema by explaining the semantic effect of supplying `board` (workspace labels plus the board's own vs workspace labels only) rather than just its accepted formats.

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 (labels) and precisely scopes what set is returned, so an agent knows this reads labels rather than mutating them. The verb is only implied by the tool name, and it never names a sibling, but the purpose is clear.

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 explains the two modes (with `board` vs without), which is effectively guidance on how to call it, but gives no explicit when-to-use vs alternatives such as create_label, and no note that list_workspaces is needed first for the workspace slug.

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 readOnlyHint=true and openWorldHint=false. The description still adds real behavioral value by disclosing the scoping rule that only invitations sent to the verified email address are returned, plus the shape of what comes back.

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 tight sentences: the resource and scoping rule come first, and the routing pointer to the sibling follows. 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 simple read-only list tool with no output schema, the description covers what is returned (workspace, board, role, inviter) and how it relates to the sibling action tool. Only pagination/ordering behavior is unaddressed, 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?

The sole parameter (response_format) has 100% schema description coverage, including enum meanings, so the schema does the heavy lifting. The description adds nothing about response_format, which is the expected baseline when coverage is complete.

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 exact resource (pending invitations) and scopes it to the caller's verified email address, enumerating returned fields (workspace, board, role, inviter). It also distinguishes itself from respond_to_invitation, though the listing verb itself is only implied by the tool name rather than stated.

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?

By stating that respond_to_invitation 'accepts or declines one', it effectively routes the agent: use this tool to see invitations, use the sibling to act on them. It gives clear context but no explicit 'when not to use' or prerequisites.

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 openWorldHint=false, so safety is covered. The description adds genuinely useful behavior — default sort order (newest change first) and the categories of notifications returned — but says nothing about pagination behavior even though a cursor parameter exists.

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 efficient sentence with the resource and ordering front-loaded. The 'sol2flow:' branding prefix is minor noise that earns no informational value.

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, no-required-param list tool with no output schema, the description covers what is returned and in what order. The absence of explicit pagination and unread-filter guidance is a small gap but not disqualifying.

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 75%, so the schema documents limit, cursor, and response_format on its own; the only undocumented parameter is unread_only. The description does not add syntax or 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?

The description states a clear verb+resource ('your notifications') and adds scope detail — ordering ('newest change first') and content types (assignments, mentions, comments, due dates). It is distinguishable from siblings like mark_notifications_read, though it never names 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?

There is no when-to-use or when-not-to-use guidance, and the obvious alternative (mark_notifications_read) is not mentioned. Usage is only weakly implied by 'your notifications'.

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 openWorldHint=false, so safety is covered; the description adds a real behavioral constraint not in the annotations — guests cannot list workspace members. It says nothing about result ordering or pagination behavior beyond what the cursor parameter implies.

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 tight sentences, front-loaded with what is returned before the caveat. The "sol2flow:" prefix is minor noise but the rest earns its place with no 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 six-parameter read tool with full schema coverage and annotations, the description supplies the two things structured fields don't: the shape of the result (name, @username, role) in lieu of an output schema, and the guest permission boundary. Only alternative-tool routing is absent.

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 six parameters (role, limit, query, cursor, workspace, response_format) are fully documented in the schema and the baseline is 3. The description adds almost no parameter-level meaning beyond hinting at role as a returned attribute.

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 resource (members of a workspace) and enumerates the returned fields (name, @username, role), so the agent knows exactly what it retrieves. It does not explicitly distinguish itself from siblings like list_workspaces or whoami, which is the only gap.

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?

"e.g. to find whom to assign" gives one concrete usage context, and the guest restriction acts as an implicit when-not condition. However, no alternative tool is named and no broader when-to-use guidance is offered, leaving usage mostly inferred.

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 openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: default ordering is by last change, oldest first, and archived tasks are excluded unless include_archived is set – non-obvious defaults an agent would otherwise guess wrong.

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 core scope, and the important defaults (ordering, archived) land in the second sentence. The first sentence is a dense run-on filter list, but no sentence 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 no output schema and 13 optional parameters, the description covers scope, default ordering, and the archived/updated_since behaviors an agent needs. It does not describe pagination behavior (cursor/limit), which is the main remaining gap, but overall it is complete enough 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 description coverage is 92%, so the schema already documents nearly every parameter, establishing the baseline of 3. The description reinforces a few key semantics (assignee accepts "me"/username/name, updated_since meaning, ordering), but adds little beyond what the schema text 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 (list) and resource (tasks), plus its exact scope: tasks on a board or on every board of a workspace. It enumerates the filter dimensions, so an agent can distinguish it from get_task (single task) and search without opening either 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 clear conditional guidance: use `updated_since` for recently changed items, and `include_archived` is required to see archived tasks. It stops short of naming sibling alternatives (e.g. search vs list_tasks), so it is strong context but not a full when/when-not routing statement.

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 openWorldHint=false, so the safety profile is covered. The description adds real behavioral value on top: result ordering ("newest first") and a result-visibility model ("You see your own entries; board and workspace admins see more"). Pagination behavior is left unexplained, keeping it below 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?

A single dense sentence that front-loads the resource and ordering, then the optional filters, then the permission scope. It earns its words, though the leading "sol2flow:" product prefix is noise for an agent.

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 mentions ordering and result scoping, and annotations cover read-only safety. For a nine-parameter listing tool the gaps are minor: nothing on pagination or truncation, but limit/cursor are self-documented in the schema.

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 all nine parameters including formats and defaults. The description only echoes the filter concepts (board, task, person, period) without adding syntax or edge-case meaning, 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 names a specific resource (logged time entries) and scope (a workspace, optionally narrowed to one board, task, or person, over a period), so an agent can distinguish it from log_time and update_time_entry. It stops short of explicitly contrasting itself with its siblings, which is what a 5 would require.

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 filtering vocabulary (board/task/person/period) and by the permission note, but the description never states when to reach for this tool versus get_timer, log_time, or update_time_entry, nor any exclusion. Adequate but leaves the routing decision to the caller.

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 openWorldHint=false, so safety is covered. The description adds output-shape context (slugs plus your role), which is beyond the structured fields, but says nothing about ordering, count limits, or emptiness. With annotations carrying the safety profile, a 3 is appropriate.

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 with no filler; the highest-value information (workspaces and their slugs) is front-loaded. The leading "sol2flow:" server tag is slightly noisy but costs nothing material.

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-required-parameter read tool with no output schema, the description supplies the missing return-value context (slugs and role), which is the main thing an agent needs. Safety is covered by annotations, so little is left unstated.

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 sole parameter (response_format) is fully documented in the schema, including its enum values. The description adds no parameter detail, so the baseline 3 for schema-driven parameter semantics 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?

The description names a specific resource ("the workspaces you can open") and goes further by stating what comes back: slugs and your role. The 'List' verb lives in the title rather than the description text, but a reader immediately understands the scope and cannot confuse it with list_boards or list_tasks.

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?

By tying the returned slug to "the `workspace` parameter of other tools," it implies this is called first when a workspace-scoped tool needs an ID. That is useful implicit routing, but there is no explicit when-to-use, no when-not-to-use, and no named alternative or prerequisite.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's added value comes from the semantics it supplies: the 1-minute-to-24-hour duration envelope and the default end-time behavior when started_at is omitted. It still omits the practical consequence of non-idempotency (repeated calls create separate entries) and any auth/workspace constraints.

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 tight sentences with the tool's identity and the key temporal default front-loaded; every clause carries information 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 5-parameter mutation with no output schema, the description covers the two behaviors least obvious from structure: duration bounds and the default end time. It says nothing about task identifier formats or workspace defaults, but the schema already covers those at 80% coverage.

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 80%, so task, duration, workspace, and started_at are already documented in the schema, including the same duration range. The description only restates the duration envelope and notes the note field is optional, adding little meaning beyond the structured fields.

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 verb+resource: 'log time spent on a task', with a stated duration bound and optional note. It is distinguishable from time-adjacent siblings like start_timer/stop_timer by describing a completed entry rather than a running timer, but it never names those alternatives to make the distinction 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 by the verb and the 'Without started_at the entry ends now' clause, which hints at the backdated-vs-live distinction. However, there is no explicit guidance on when to use this versus start_timer, stop_timer, or update_time_entry, and no prerequisites or error conditions are 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 disclose that this is a mutating, idempotent, non-destructive operation. The description adds the source of ids and the all-notifications option, but does not add details about permissions, side effects, or error behavior 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?

It is a single compact sentence with no unnecessary elaboration. The 'sol2flow: mark notifications read:' prefix is somewhat redundant with the tool name and title, but it does not obscure the useful 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 low-complexity mutation tool with annotations covering idempotency and safety, the description is mostly adequate. However, with zero required parameters, it leaves the default behavior ambiguous when neither ids nor all is provided, and it omits the schema's maxItems=50 limit.

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 50%; the all parameter is already documented in the schema. The description adds that ids come from list_notifications and implies an either/or relationship with all, but it does not mention the maxItems=50 constraint or clarify mutual exclusivity or default behavior when both are omitted.

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 (mark notifications read) and immediately clarifies the two scopes: given ids from list_notifications, or all notifications. An agent can tell exactly what this tool does 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 gives clear context for the two usage modes: ids should come from list_notifications, or the caller can mark all. It does not explicitly state when to prefer one mode over the other or what happens if neither is supplied, but the routing context is strong.

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-destructive, idempotent, non-read-only behavior, so the bar is partially met. The description adds genuinely useful behavior beyond that: a cross-board move assigns a new key while the old key still resolves, which is non-obvious identity semantics an 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?

A single front-loaded sentence leads with the verb and resource before branching into the finer cases. It is dense but has no filler; the trailing parenthetical about keys is the only mild overload.

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 mutation tool with full schema coverage and no output schema, the description covers the meaningful behaviors, including the cross-board key remapping. It omits return/result format and any permission or workspace prerequisites, but those are secondary given the annotations and rich schema.

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 every parameter is already documented in the schema, making 3 the baseline. The description echoes position values (top, bottom, before/after) and board/list behavior, but adds little syntax or format beyond what the schema already states.

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 (move) and resource (a task) and then disambiguates what 'move' means: list and/or position, or another board's list. This clearly separates it from siblings like update_task and archive_task, which handle field edits and archiving respectively.

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 makes the usage context clear by enumerating the move modes (position, list, cross-board). However, it never explicitly contrasts itself with alternatives such as update_task for field changes or archive_task for removal, so the agent must infer the boundary.

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 flag destructiveHint=true and idempotentHint=false, but the description adds substantive consequence detail: accepting joins the workspace (and board), and declining can't be undone. This tells the agent the state changes and irreversibility beyond the flags, though it omits permission/auth requirements and what a repeat call does.

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 source of the input, then consequences. No filler; 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 non-idempotent, destructive, two-parameter mutation tool with annotations present and no output schema, the description covers action, source, and irreversible consequences adequately. Minor gap: no mention of error behavior (e.g., already-processed invitation) or auth requirements.

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 50% schema coverage, the description compensates by explaining what each response value actually does ('accepting joins the workspace...') and anchoring invitation_id to list_my_invitations, adding meaning beyond the bare enum in 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 pair ('accept or decline') and resource ('one invitation'), scoped to items from list_my_invitations. An agent can distinguish this from sibling tools like mark_notifications_read or list_my_invitations 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?

Explicitly ties usage to invitations obtained from list_my_invitations and clarifies the effect of each branch (accept joins the workspace/board). It does not name an alternative tool for handling invitations, but the intended context is clear.

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 and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: archived boards/tasks are silently excluded from results, and omitting `workspace` in a multi-workspace setup fans the search out across all of them.

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 no filler; the resource/field enumeration comes first and the scoping caveats (archived, multi-workspace) follow. Every clause carries information an agent would otherwise have to guess.

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 3-parameter read-only search with no output schema, the definition covers resource scope, matchable fields, exclusion rules, and defaulting behavior adequately. It does not describe the shape of results or ordering, though the response_format enum partially signals the return form.

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 67%, and the description meaningfully extends the undocumented `query` parameter by spelling out what it matches (board name/key; task title/key/description). The workspace fallback rule is restated from the schema, and response_format is left to its enum description, but the added query semantics exceed the baseline for this coverage level.

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 (find) with two specific resources (boards, tasks) and enumerates the matchable fields (name, key, title, description, key format like PRD-12). The sibling listing is full of singled-resource lookups (list_boards, list_tasks, get_task), so naming both resource types plus the free-text matching makes this tool's distinct role 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 'like ⌘K in the app' analogy gives a clear mental model for when to reach for this over list_*/get_* tools: fuzzy keyword lookup rather than enumeration or ID fetch. It also states the archived-exclusion and multi-workspace fallback conditions. It stops short of an explicit 'prefer this over list_tasks when you don't know the exact key' statement.

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 the important side effect that annotations cannot express: only one timer runs at a time, so starting this one stops a timer on another task and logs its time. That is genuine behavioral context beyond destructiveHint=true. It omits any note about non-idempotency or repeated-call behavior, though.

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 tight sentences with the core action first and the critical side-effect constraint second. Every clause earns its place 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 two-parameter mutation with full schema coverage and a complete annotation set, the description supplies the one behavior an agent genuinely needs (the single-timer override). Return value info is unnecessary since there is no output schema, though a pointer to get_timer for verifying state would have been a nice touch.

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% — the schema already explains that 'task' accepts a key, URL, or id and that 'workspace' defaults to the configured workspace. The description adds no parameter-level meaning beyond that, 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 ("start your timer on a task"), which cleanly separates it from stop_timer and get_timer in the sibling list. It never names the alternatives explicitly, but the verb alone 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?

Usage is implied by "start your timer on a task" and the one-timer rule, but there is no explicit when-to-use/when-not guidance and the obvious alternative (stop_timer) is never referenced. The scope of 'task' acceptance is only discoverable from the schema.

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-destructive, idempotent, non-readOnly behavior, so the safety profile is covered. The description adds genuine value beyond that by disclosing the side effect — elapsed time is logged onto the task — which is the key consequence an agent needs to know.

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 compact sentence with the action and effect front-loaded. The 'sol2flow:' vendor prefix is minor noise, but nothing else 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 zero-parameter, non-destructive action whose annotations carry the safety profile and whose return values needn't be described (no output schema), the description covers the essentials. It could optionally note behavior when no timer is running, but that is minor.

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 per the baseline rule a 4 is appropriate; there are no arguments whose semantics need explaining and the description correctly implies a no-argument invocation.

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 ('stop') and resource ('your running timer') and adds the outcome ('its time is logged on the task'). An agent can distinguish it from start_timer and get_timer from the description 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 implied by the phrase 'stop your running timer' — the agent can infer it applies when a timer is active — but it never names alternatives such as get_timer, log_time, or start_timer, nor states the when-not condition (e.g., no timer running).

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 safety (readOnlyHint=false, destructiveHint=false) and idempotency. The description adds real behavioral value beyond that: it discloses where the task lands (its original list, or the first list if that list is gone), which no structured field states.

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 compact sentence with the key behavior front-loaded and the edge case in a parenthetical. The 'sol2flow:' namespace prefix is slightly extraneous but costs almost nothing in space or comprehension.

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 idempotent, non-destructive restore tool with full annotation coverage and a fully described schema, the description covers the essential gap (restoration target). No output schema exists, so return-value documentation is not required; nothing critical 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 both parameters (task's key/URL/id, and workspace slug with default) are fully documented in the schema. The description adds no additional parameter meaning, which is the expected baseline 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?

Specific verb ('bring an archived task back') plus a clear resource ('archived task'), and it is the obvious inverse of the sibling archive_task. It does not name that sibling explicitly, so it falls just short of the routing clarity a 5 demands.

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 phrase 'bring an archived task back', which conveys restoring a previously archived task. There is no explicit when-to-use guidance and no stated prerequisites, so it is only minimal viable.

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=true, and idempotentHint=true. The description adds no context about what gets destroyed, permission requirements, or whether it fails if no link exists. With annotations covering safety, the description should at least confirm the destructive nature or side effects, but it does not.

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 concise sentence that front-loads the main action and then adds a secondary condition. It is efficient but could be slightly clearer with a verb like 'removes' instead of 'remove' to match the imperative style of tool descriptions.

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 is a destructive mutation with no output schema and 4 parameters, the description is minimal. It does not explain the return value, error cases, or the scope of impact (e.g., whether it removes all links of the specified kind between the two tasks). An agent would need to infer these from annotations and schema alone.

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 75%, so the schema already documents most parameters (task, other_task, workspace). The description only mentions the 'kind' parameter's behavior ('with kind only that kind of link'), which is useful but already implied by the enum. It adds marginal value beyond 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+resource: 'remove the link(s) between two tasks'. It references the 'kind' filter condition, which adds precision to the operation. However, it does not differentiate from the sibling 'link_tasks' explicitly, which would have helped an agent choose between link and unlink.

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 when-to-use guidance is provided. The description does not explain when to use this tool versus alternatives like link_tasks, nor does it mention prerequisites (e.g., the link must exist). It only describes the effect of the 'kind' parameter.

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=true, idempotentHint=true, covering the safety profile. The description adds the reference-resolution semantics (1 = first, text matching) but does not disclose the destructive implications flagged by annotations, e.g. what happens if text matches multiple items or how edits resolve.

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 followed by the item-reference rule; every clause carries information. The 'The item: its id' phrasing is slightly telegraphic but not wasteful.

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 no output schema, the description covers the trickiest part (item resolution) but omits behavioral consequences of the destructive edit and says nothing about the `done`/`text` payload semantics. Adequate but with clear gaps.

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 60%, so the schema already documents item, task, and workspace. The description usefully adds the '1 = first' numbering detail and the dependency between item and task, but leaves `done` and `text` (undocumented in both schema and description) unaddressed, matching the baseline 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 names a specific verb set (tick/untick, change text) and a specific resource (a checklist item), which cleanly separates it from siblings like add_checklist_items or update_task. It does not explicitly name a sibling, so it stays at 4 rather than 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?

It explains how to reference the item (its id from get_task, or number/text when `task` is supplied), which is useful invocation context. But it gives no when-to-use/when-not guidance or alternatives versus other checklist or task-editing tools, so usage 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?

Annotations already declare destructive=true, idempotent=true, and readOnly=false. The description adds real value beyond them: it clarifies partial-update semantics, that null clears dates/estimate, that labels/assignees are replaced wholesale versus add/remove deltas, and that changes apply step by step with a per-step answer. Auth/permission behavior is not covered.

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 verb and resource, then a dense clause listing the fields and the two key rules. Every sentence carries information, though the "sol2flow:" prefix adds little.

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 14-parameter mutation with no output schema, the description covers the operational model well: field grouping, null semantics, replace-vs-delta arrays, and the step-wise response. Remaining gaps (workspace scoping, task identifier) are adequately handled by the schema.

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 only 43% across 14 parameters, so the description must compensate, and it largely does by grouping the mutators (title, description, dates, estimate, labels, assignees, list) and explaining the replace-vs-delta distinction. Only workspace and the task key format are left to the schema, which documents them.

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 (change) and resource (a task) and enumerates exactly which fields can be altered: title, description, dates, estimate, labels, assignees, and list. An agent can distinguish it from create_task, move_task, and archive_task 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 partial-update rule ("Fields left out stay as they are") gives useful context for when this tool applies, but the description never names alternatives. Notably, it includes list-move behavior while a sibling move_task exists, and there is no guidance on which to prefer.

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 mutation (readOnlyHint=false), idempotency, and destruction risk. The description adds value the annotations cannot: '(null clears it)' explains the null-clearing behavior, and 'A running timer only takes a note' discloses that editable fields are restricted for running entries. It does not mention auth or rate limits, but the added constraints are substantive and consistent with 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 sentence plus a short fragment, front-loaded with the operation and the id source. 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?

For a 4-param mutation tool with annotations covering the safety profile and no output schema, the description covers the editable fields, null semantics, running-timer restriction, and id sourcing. It is close to complete; a brief note on what the edit returns or whether omitted fields are untouched would close the remaining 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 coverage is 50% (duration and started_at documented; note and entry_id not). The description compensates by naming the editable fields ('start, duration or note'), explaining the null-clears semantics for note, and sourcing entry_id from list_time_entries. It adds genuine meaning beyond the schema on the undocumented parameters.

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?

"change one of your time entries" gives a specific verb+resource, and the description enumerates the editable fields (start, duration, note), so an agent knows exactly what this mutates. It points to list_time_entries as the id source, distinguishing it from sibling readers, though it does not contrast with write siblings like log_time or start_timer.

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: '(id from list_time_entries)' tells the agent where the id comes from, and 'A running timer only takes a note' is a real constraint. But there is no explicit when-to-use-this vs log_time/start_timer guidance or when-not-to-use conditions.

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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond that by disclosing that key details require sol2flow 1.8+ (a version-dependent behavior) and by enumerating the returned fields, which matters because there is no 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?

A single dense sentence followed by the two-word 'Start here' call to action. It is front-loaded and wastes no words, though the long parenthetical chain makes it slightly harder to scan than a bulleted breakdown would be.

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 carries the burden of describing return values, and it does so by listing account, key, instance, and workspace fields. The only real gap is the absence of guidance on how the default workspace relates to the sibling list_workspaces 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?

The single response_format parameter has 100% schema coverage with an inline enum explanation ('markdown (default): compact text; json: the API data'), so the schema does the work. The description adds nothing about the parameter, which is the expected baseline when coverage is complete.

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 enumerates exactly what identity data the tool returns: the account (name, username, time zone), the key (name, scope, expiry), the instance/API version, and workspaces with the default. That is a concrete resource definition an agent can match against the 'who am I' intent, though it never states a verb and does not distinguish itself from the sibling list_workspaces, which overlaps on its workspace output.

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?

'Start here' is a genuine orientation cue, implying this is the first call an agent should make when it needs context about the credential it holds. However, no alternative is named and no condition is given for choosing this over list_workspaces, even though both surface workspace information.

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