Kangram

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that membership is immediate, that no invitation is created or accepted, that owner/admin permission is required, and that the owner role cannot be granted. It omits edge behavior such as what happens if the username is already a member or unknown, which is the only meaningful gap for a state-mutating tool.

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

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

Two tight sentences: purpose and mechanism first, permission and role constraints second. No filler, no restating of the name, and every clause carries information the caller needs.

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

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

For a three-parameter mutation tool with no output schema and no annotations, the description supplies the essential context: immediate grant, no invitation, permission level, and role ceiling. Only the duplicate/invalid-username behavior is left unstated, which is a minor rather than blocking gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with board_id, username, and the role enum all documented inline, so the schema already does the heavy lifting. The description only reinforces the role constraint ('cannot create or assign the owner role'), adding marginal value beyond what the schema 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 and resource ('add a user directly to a board') and immediately clarifies the mechanism ('they become a member immediately, with no invitation to accept'), which implicitly separates it from invite_board_member among the siblings. An agent can distinguish it from the invitation/ownership siblings 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?

Tells the agent when to use it ('add a user directly... no invitation to accept') and names the access restriction ('Owner/admin only'), which is real usage context. It stops short of naming invite_board_member explicitly as the alternative path, so selection between the two still requires a small inference.

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

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

No annotations are provided, so the description carries the full behavioral burden and largely fails to. It does not say whether the operation requires write permissions, whether it is idempotent, what happens on a duplicate title, or what the response contains. 'Add' implies mutation, but nothing beyond that is disclosed.

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

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

Two tight sentences with the action front-loaded and no filler. The second sentence largely restates information the schema already carries, so it is not entirely earning its place.

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

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

For a three-parameter mutation tool with no annotations and no output schema, the description is only minimally adequate. An agent gets the basic action and task identifier, but nothing about side effects, failure modes, or result shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are documented in the schema, making 3 the baseline. The description's only addition is noting that board_id and task_number jointly identify the task, which is a small scoping insight but is essentially implied by the schema's own parameter descriptions.

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

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

The description states a specific verb and resource: adding a new item to a task's checklist. It is clearly distinguishable from delete_checklist_item, update_checklist_item, and list_checklist by the verb. It stops short of naming those siblings explicitly, so a 5 is not warranted.

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 phrasing 'Use this to add...' implies usage but never states when to choose this over update_checklist_item or list_checklist, nor any preconditions. The one concrete piece of guidance — supply board_id + task_number to identify the task — is really parameter guidance rather than usage routing.

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

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

No annotations are provided, so the description carries the full burden, yet it discloses almost no behavior: no mention of required permissions, whether the comment notifies task watchers, whether it is editable afterward, or what the response contains. For a mutation tool with zero annotation coverage, this is a significant gap.

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 identifying inputs. The second sentence is largely redundant with the schema's parameter descriptions, but there is no padding or filler.

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

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

A mutation tool with no annotations, no output schema, and no explanation of permissions, side effects, or return value. An agent can call it, but cannot predict its effects or failure modes from the definition 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 100%, so all three parameters (text, board_id, task_number) are already documented in the schema. The description's restatement of 'board_id + task_number to identify the task' adds no syntax or constraint detail beyond that baseline.

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

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

States a specific verb+resource: 'add a comment to a specific task.' This is unambiguous and distinguishable from the siblings list_comments and delete_comment, though the description never names or contrasts 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?

The description says nothing about when to use this versus alternatives (e.g., update_task for editing, list_comments for reading) or any preconditions. It only explains how to identify the target task, which is identification guidance rather than usage guidance.

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

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

With no annotations, the description must carry behavioral disclosure. It usefully states that the operation is non-destructive ('without deleting it') and hides the board from active workflows, but it omits permissions, reversibility details, and effects on related tasks or members.

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

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

The description is a single front-loaded sentence with no wasted words. It communicates the core action and its non-destructive nature efficiently.

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

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

For a simple one-parameter mutation with no output schema, the description is minimally adequate. However, because no annotations are provided, it leaves out important context such as whether the archive is reversible, permission requirements, and what happens to the board's 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% for the single board_id parameter, so the schema already explains the argument. The description adds no additional parameter meaning, making the baseline 3 appropriate.

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

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

The description states a specific action (hiding/archiving a board) and distinguishes it from deletion with 'without deleting it'. It does not explicitly name the sibling restore_board or other board-management alternatives, 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 gives a usage condition ('hide a board from active workflows') but does not specify when to choose this over related tools like restore_board, update_board, or delete operations. Usage is implied rather than fully guided.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the destructive side effect ('Unbinds any previous binding first'), the authorization requirement (owner/admin of the target board), and the runtime consequence (bot commands in the group will act on this board). These are exactly the behavioral traits an agent cannot infer from the 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?

Purpose is front-loaded in the first sentence, followed by effect, side effect, permission, trigger condition, and param formats in a logical order. Slightly dense but every sentence contributes actionable information, so no meaningful trimming is possible without losing 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 2-param mutation tool with no annotations and no output schema, the description covers the important ground: what it does, its destructive side effect, the auth requirement, and parameter formats. It is nearly complete, though it does not say what the tool returns or how failures (e.g. non-admin actor) surface.

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 both parameters, establishing a baseline of 3. The description restates the boardRef accepted formats and adds a URL example, but adds little meaning beyond what the schema description already provides; group_chat_id auto-detection is likewise already 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 and resource ('Bind (link) a board to a Telegram group chat') and immediately explains the effect: the board becomes the group's primary board and bot commands act on it. An agent can distinguish this from siblings like move_board or set_board_setting 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?

Explicitly tells the agent when to invoke it ('when a user asks to set, link, bind, or assign a board to a chat/group') and states the precondition that the actor must be an owner/admin. It does not name a contrasting alternative tool for the case where binding is not appropriate, so it falls short of the top mark.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the authorization model (inviter or board admin only), which the schema does not. It says nothing about irreversibility, whether the invitee is notified, or what happens to the invitation record after cancellation, leaving meaningful gaps for a mutation tool.

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

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

Two short sentences with zero filler; the action and its scope come first, followed immediately by the permission constraint. Nothing is redundant.

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

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

For a one-parameter mutation with no annotations and no output schema, the description covers purpose and the key access constraint. It could still note whether cancellation is reversible or what the caller should expect on success, but the essentials 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 description coverage is 100% and there is a single required parameter, so the schema already fully documents invitation_id. The description adds no syntax, format, or sourcing guidance (e.g., where to obtain the ID from list_pending_invitations), 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 ('cancel a pending board invitation'), which is unambiguous and distinguishable from nearby tools like invite_board_member and respond_to_invitation. It does not, however, explicitly name which sibling to use in adjacent scenarios, so it stops short of full sibling differentiation.

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

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

It gives a real prerequisite — 'Only the original inviter or a board admin can cancel' — which tells the agent who may invoke it. It does not say when to prefer this over respond_to_invitation (invitee declining) or remove_board_member (removing an existing member), so routing guidance is only implied.

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

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

With no annotations, the description carries full burden and delivers: caller becomes owner, board lands in the caller's personal namespace with a fresh unique code, source read-access requirement, and that authorization is 'enforced imperatively in execute'. These are exactly the side-effect and permission traits an agent needs before calling a mutation tool.

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

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

Front-loaded with the core action and the copy/exclude semantics before secondary details (ownership, namespace, authorization). Dense but each sentence carries information; only slight tightening would be possible.

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

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

No output schema exists, and the description does not describe the return value (e.g., the new board's id/code), which is a minor gap. Otherwise it is complete for a clone mutation: source, resulting content, ownership, and authorization are all covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already documents code (auto-generated if omitted) and title ('<source title> (copy)'). The description adds only the framing of a 'fresh unique code', so it adds little beyond structured fields — 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?

Specific verb+resource with explicit scope: clone a board copying 'the workflow not the data: statuses + board files + board title', and it enumerates the exclusions (tasks, comments, members). This clearly distinguishes it from create_board and other board-mutating siblings.

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

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

The copy/exclude breakdown implicitly tells an agent when this tool applies (duplicating a workflow template) rather than create_board or update_board. It states the authorization conditions (board member OR any viewer of a public board), but never names an alternative tool explicitly.

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

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

With zero annotations, the description carries the full burden and delivers: immediate org membership with board access via role inheritance, no personal namespace, no login capability, auto-issued first API key returned in plainKey that is never shown again, and the owner/admin permission requirement. These are exactly the irreversible and authorization facts an agent needs before invoking.

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

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

Four dense sentences that each carry non-redundant information, with the core action front-loaded in sentence one. The parenthetical loadings ('User type=\'agent\'', 'board access via role inheritance') add a little friction but 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?

No output schema exists, and the description compensates by disclosing the key return artifact (plainKey, single-display) as well as membership, namespace, login, and permission behavior. Nothing material an agent needs to call this mutation correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented with constraints and the role enum semantics. The description adds only marginal param-level meaning ('board access via role inheritance'), 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 ('Create a non-human agent account (User type=\'agent\')') scoped to an organization namespace, which clearly separates it from human-membership siblings like add_board_member and invite_board_member. An agent can identify the target entity type 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?

Gives a clear activation context (provisioning a non-human agent identity) plus the prerequisite 'Requires organization owner/admin.' It never explicitly names the alternative path for adding humans, so there are no exclusions, but the context for when this tool applies is unambiguous.

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

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

No annotations exist, so the description carries the full burden. It does disclose one genuinely useful side effect — a default status workflow is created alongside the board — but says nothing about permissions/auth, whether the board binds to the active group chat, idempotency, or what happens when a namespace_slug collides.

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 or redundancy. It is efficient, though arguably too sparse for a four-parameter creation tool, which keeps it from a 5.

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 annotations and no output schema, the description must carry the behavioral and return-value burden. It covers the core action and the schema covers parameters, but an agent still cannot tell what is returned, what the safety profile is, or how this differs from clone_board.

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%: every one of the four optional parameters has its own description, examples, and a cross-reference ('Use list_namespaces to discover available slugs'). The description adds no parameter meaning beyond that, 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?

The description names a specific verb ('initialize') and resource ('board') and adds a concrete detail — the default status workflow — so an agent knows what gets created. It does not differentiate from near-siblings like clone_board or create_organization, so it stops short of a 5.

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

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

It says to 'use this command' but never states when this is the right choice versus alternatives such as clone_board (copy an existing board) or list_boards. No preconditions, no exclusions, and no routing guidance 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?

With no annotations, the description carries the full burden and does well: it discloses the owner-only permission requirement and the critical one-time exposure of the client_secret ("shown ONCE — store it securely"). It omits rate limits, reversibility, or what happens to the client after registration, keeping it short of a 5.

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

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

Three tight sentences, front-loaded with the core action, then the security-relevant return behavior, then the permission constraint. Every sentence earns its place with no filler.

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

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

There is no output schema, and the description compensates by explaining the returned credentials and their one-time nature. Combined with 100% schema coverage, an agent has what it needs, though permission/ownership semantics beyond "Owner-only" are left thin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so name, scopes, and redirect_uris are already fully documented in the schema (including scope enum and redirect URI rules). The description adds no parameter-level detail beyond that, 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 ("Register a new OAuth2 client") and its purpose (letting a third-party app authenticate users). It is easily distinguishable from sibling tools like list_oauth_clients and revoke_oauth_client.

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

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

The scope of use is implied (registering a client for Login with Kangram) and it flags "Owner-only", but it never explicitly states when to use this versus alternatives such as revoke_oauth_client or list_oauth_clients, nor any prerequisites for the flow.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose two meaningful side effects: a namespace slug is derived from the name and the caller becomes owner. However, it omits auth/permission requirements, whether the name must be unique, what happens on slug collision, and whether the operation is reversible.

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

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

Three short sentences, front-loaded with the action and followed by consequences and usage trigger. Every sentence carries distinct information with no boilerplate or repetition.

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

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

For a single-parameter create tool with no output schema, the description covers action, side effects, ownership outcome, and the usage trigger, which is enough to call it correctly. It could be more complete by noting permission requirements or name-uniqueness behavior, but nothing essential 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?

Only one parameter exists and the schema already documents it at 100% coverage, including the slug-derivation note that the description repeats. The description adds no new syntax, format, or constraint information beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Create a new organization') and immediately clarifies the aliases an agent may encounter ('namespace, organization, or workspace'), which is critical since sibling tools like list_namespaces and create_board use different terminology for the same domain. No competing create tool exists among the siblings, so an agent can route confidently.

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 final sentence gives explicit triggering context ('Use this when a user asks to create a namespace, organization, or workspace'), which resolves real vocabulary ambiguity in this toolset. It stops short of stating exclusions or prerequisites (e.g., plan limits, required role), so it is clear but not exhaustive.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about required permissions, side effects on the existing workflow, or whether the new status is appended or placed by index. For a mutation tool with zero annotation coverage this is a real gap.

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

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

One short, front-loaded sentence with no padding. It is efficient, though the brevity comes at the cost of the missing guidance noted elsewhere.

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

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

The rich schema covers all inputs and defaults, so the agent can construct the call. What is missing is behavioral context: authorization needs, effect on existing status ordering, and confirmation of the created result, none of which annotations or an output schema supply.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each of the five parameters documented including defaults (board_id defaults to active board, code derived from name). The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('add') and resource ('statuses to board workflow'), so an agent knows it creates a status rather than updating or deleting one. It does not, however, differentiate itself from siblings like update_status, delete_status, or reorder_statuses, which operate on the same resource.

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

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

The phrase 'Use this command to add new statuses' is a bare directive with no conditions, prerequisites, or alternatives. It never says when to prefer this over update_status or reorder_statuses, or what context (board admin, existing board) is required.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a non-obvious default (falls back to the active board when board_id is omitted), which is genuine context beyond the schema. However, it says nothing about permissions required, side effects, or whether the caller is notified.

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 clauses, no filler, and the more actionable routing advice comes first. It is efficiently sized for the message, though extremely terse relative to the 11-parameter surface it fronts.

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 11 parameters and no annotations or output schema, the description covers only the board-routing behavior. The schema documents every parameter at 100%, which compensates, but an agent still learns nothing about side effects, error conditions, or the shape of the created task.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds routing semantics for the board parameter ('deterministic routing' vs active-board default) but does not explain subtasks, telegram linking, or the enum priority beyond what the schema already documents.

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 combination ('add a task'), which is clearly distinguishable from siblings like create_board, update_task, or move_task. It does not explicitly name a sibling it is not, but the name and phrasing leave no ambiguity about what gets created.

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

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

The description gives one conditional: supply boardId for deterministic routing, otherwise the active board is used. That is useful routing guidance but not a when-to-use-this-vs-alternatives statement; it never mentions update_task, list_tasks, or when not to create a 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?

With no annotations, the description carries the full behavioral burden. It discloses the cascade (key revocation, membership removal, task unassignment), the fallback behavior when history rows block deletion (deactivate instead of delete), the returned status value, and permission requirements. This is exactly the kind of context an agent needs before invoking a destructive tool.

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

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

The description is a single, front-loaded sentence that packs a lot of information without waste. It could be slightly tightened, but it remains readable and efficient.

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

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

For a destructive tool with no annotations and no output schema, the description covers all critical aspects: what gets destroyed, the fallback deactivation, the returned status, and auth requirements. An agent can invoke it correctly with confidence.

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% – both agent_username and namespace_slug are fully documented in the schema. The description adds no parameter-specific details beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete an agent account') and immediately enumerates what deletion entails (revokes API keys, removes memberships, unassigns tasks, hard-deletes user). This distinguishes it clearly from siblings like revoke_agent_key and delete_task, which handle narrower operations.

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

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

The description implies when to use it: to fully remove an agent. However, it does not explicitly contrast with restore/revoke alternatives or state when NOT to use it. The permission requirement ('Requires organization owner/admin') adds a useful precondition.

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?

No annotations are supplied, so the description carries the full behavioral burden, and it does not disclose whether deletion is permanent or reversible, what happens to item ordering, or whether specific permissions are required. For a destructive mutation this is a meaningful gap.

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 action front-loaded and no filler. There is no waste, though the second sentence ('Provide item_id') is largely redundant with the schema.

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

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

A single-parameter tool with no output schema needs little description, but as an unannotated destructive operation it should at least signal permanence or permission requirements. It is minimally viable without being 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 100% with a single documented parameter, so the schema already explains that item_id is the checklist item ID to delete. The description's 'Provide item_id' adds nothing 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 ('remove a checklist item') plus scope ('from a task'), so an agent can identify the operation precisely. It does not distinguish itself from siblings such as delete_task, delete_comment, or delete_status that share the same delete pattern.

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 says only 'Use this to remove a checklist item from a task,' which restates the purpose rather than giving when-to-use conditions, prerequisites (e.g., does the task need to exist, are there permission requirements), or when to prefer update_checklist_item instead. No exclusions or alternative routing 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?

With no annotations, the description carries the full burden; it discloses the authorization model (author or owner/admin) and the required context (board_id + task_number), which is genuinely useful. It does not say whether deletion is permanent or reversible, or how failures (missing comment, insufficient permission) surface.

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 action and the permission constraint front-loaded, followed by the required inputs. Minor filler in 'Use this to', but nothing extraneous.

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 three-parameter delete with a 100%-covered schema, no output schema, and no annotations, the description covers the essentials: what it does, who may do it, and what must be supplied. The main omission is the irreversibility of the operation, which matters for a destructive call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each of the three required integers documented in the schema itself ('Board ID where the task belongs.', 'ID of the comment to delete.', 'Task number in board scope.'). The description only restates requiredness of board_id, task_number, and comment_id, adding no format or constraint detail beyond the schema, 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 and resource: 'delete a comment'. It is clearly distinguishable from the other delete_* siblings (delete_task, delete_status, delete_checklist_item, delete_agent) by resource, though it does not explicitly name or contrast 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?

The description supplies the key gating condition (only the comment author or a board owner/admin may delete), which tells the agent whether the caller is even eligible. It does not say when to prefer deletion over an alternative action or mention prerequisites such as the comment needing to exist.

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

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

No annotations are provided, so the description carries the full behavioral burden. It hints that deleting an in-use status has a dependency requiring a replacement, but does not disclose whether deletion is permanent/irreversible, what happens if no replacement is supplied while tasks use the status, or any permission requirements. For a destructive tool with zero annotation coverage this is a significant gap.

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

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

Two short sentences with zero waste, and the target-identification methods are front-loaded before the replacement condition. It is efficient, though extremely terse.

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 destructive mutation tool with no annotations and no output schema, the description should disclose permanence, error behavior when replacement is omitted, and permission needs. It covers only target identification and the replacement hint, leaving meaningful behavioral 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 100%, so the baseline is 3, but the description adds real value by clarifying the mutually exclusive lookup logic (statusId OR boardId+code) and the conditional use of replacementStatusId. That relationship is not spelled out in the schema itself.

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 (delete) plus the resource (status) and two ways to identify the target (statusId or boardId+code). This distinguishes it from siblings like update_status or create_status without opening a schema. It stops just short of explicitly naming a sibling it is not.

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 conditional "If tasks use it, provide replacementStatusId" gives one genuine when-condition. However, there is no explicit guidance on when to choose this over update_status or transition_task_status, nor any stated prerequisite such as permissions.

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

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

With no annotations, the description carries the full burden, and it does disclose one meaningful trait the name hides: the deletion is non-permanent, so the record remains recoverable. It says nothing about permissions, side effects on related data (comments, checklist items), or behavior on an already-deleted task, so significant behavioral ground is uncovered.

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

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

A single compact sentence with no wasted clauses, and the key semantic (soft delete) is front-loaded. Slightly weakened only by the 'Use this to' preamble, which adds no 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 two-parameter mutation tool with no annotations and no output schema, the description covers the most important behavioral fact (reversibility) but omits return behavior, permission requirements, and interaction with already-deleted tasks. 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 description coverage is 100%, so board_id and task_number are already documented in the schema. The description adds no syntax, format, or scoping detail beyond that, making the baseline of 3 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+resource (delete a task) and, crucially, disambiguates the operation by stating it is a soft delete ('mark a task as deleted without permanent removal'). This separates it conceptually from a hard-delete, though it does not name the sibling restore_task that would undo it.

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

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

The phrase 'Use this to...' implies the intended scenario, and the soft-delete wording hints at when to prefer it over permanent removal. However, it never states prerequisites, alternative tools (e.g. restore_task), or when-not-to-use conditions, leaving usage largely inferable rather than explicit.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses membership gating and that unknown-namespace, unknown-board, and non-member all produce indistinguishable errors (anti-enumeration semantics). It omits return shape, required scopes beyond membership, and rate limits, keeping it short of a 5.

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

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

Three sentences, front-loaded with the purpose, then the resolution algorithm, then the failure semantics. No filler and no repetition of schema text.

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 lookup with no output schema and no annotations, the description covers identity resolution, scoping, and error cases adequately. It leaves the returned board shape unspecified, though an agent can reasonably infer it returns the board entity.

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 the cross-parameter relationship the schema cannot express: namespace_slug is resolved first, then board_code is looked up within that namespace. That ordering and containment meaning is genuine 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 a specific verb+resource ('Canonical lookup for a board') and explains the exact resolution mechanism: namespace by slug, then board by 3-character code. This is clearly distinguishable from sibling list_boards (plural enumeration) and get_board_settings (settings rather than identity resolution).

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 word 'Canonical' implies this is the preferred single-board fetch path, and the error behavior hints at when it will fail, but no sibling is named and no explicit when-to-use/when-not guidance is given. An agent must infer that list_boards is the alternative for browsing.

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

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

With no annotations provided, the description carries the burden and does disclose the key behavioral traits: the read targets the root file 'AGENTS.md' and returns null when no prompt is set. It does not discuss permissions or auth, but for a read-only fetch the return/empty-case behavior is the material disclosure.

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

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

Three tight sentences: purpose first, then when to use it, then return semantics including the null case. 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?

No output schema exists, and the description compensates by explaining exactly what the return value contains and the null edge case. Nothing an agent needs to call and interpret this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single board_id parameter is already documented as 'Board ID to read the prompt for.' The description adds no syntax or constraint detail beyond that, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Fetch the board-level agent prompt') and disambiguates by naming exactly what is returned: the board's root file 'AGENTS.md'. An agent can distinguish this from sibling readers like get_project_context or list_board_files 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 says when to use it ('Read this into your context before working a board'), giving clear situational context. It stops short of naming alternatives or exclusions (e.g. project-level prompt vs board-level), so it is clear but not fully routing.

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

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

With no annotations provided, the description carries the full burden, and it does disclose the non-obvious 'effective/lazy' semantics: an unset key still returns a default rather than nothing. It also states the return shape ({ key: value } object(s)). It does not cover permissions or behavior on an invalid/unknown key, so it falls short of a 5.

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

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

Three short sentences, zero filler, and the core purpose is front-loaded ahead of the parameter mechanics and return shape. Every clause earns its place.

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

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

For a two-parameter read tool with full schema coverage, the description covers purpose, the lazy-default behavior, and the return shape despite there being no output schema. Only error/edge-case behavior (unknown key, missing board) 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 both parameters are already documented in the schema, including the 'omit to read all' behavior. The description restates this but adds no format, naming convention, or validity detail beyond it, 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 — reading a board's effective settings — and adds the scope nuance that the value may be the stored one or the default. It is readily distinguishable from the write-side sibling set_board_setting and the schema-introspection sibling get_board_settings_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 explains how to call it (pass a key for one setting, omit for all) but gives no guidance on when to prefer it over siblings such as get_board_settings_schema or get_project_context. Usage is implied by the read verb rather than stated.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses read-only, board-independent metadata and a json-schema-like return of types/defaults, and places the tool in a workflow before set_board_setting. It does not explicitly state auth requirements, rate limits, or a no-side-effects guarantee, but the read-only nature is strongly implied by 'discover' and 'metadata'.

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, front-loaded with purpose, then parameter usage, then behavioral/workflow context. Every sentence earns its place and there is no redundant 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?

There is no output schema, but the description explains the return as json-schema-like types/defaults, which is sufficient for this introspection tool. With high schema coverage for the single optional parameter and a clear read-only metadata role, the definition is complete enough for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description's statement that a key inspects one setting and omission returns all settings merely repeats the input schema's existing key description; it adds no syntax, format, or validation meaning beyond what the schema already 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 discovery task: 'discover which board settings exist and their types/defaults (json-schema-like)'. It clearly distinguishes itself from set_board_setting by positioning as a pre-write schema lookup, and its return of schema metadata separates it from sibling get_board_settings, which would return values. An agent can tell 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?

Explicitly says to call this before set_board_setting to learn valid keys and types, and explains whether to pass a key or omit it. However, it does not name get_board_settings as the alternative for retrieving current values, nor does it state when not to use this tool, so it falls short of full when/when-not/alternatives guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses scope ('across all accessible boards') and that the digest is computed on demand, plus the categories returned, but says nothing about auth requirements, cost, or whether results are cached. Adequate for a low-risk read, but not rich.

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 tightly written sentences: the first front-loads what the tool produces, the second gives the trigger questions. No filler or restated structured data.

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

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

For a zero-parameter read tool with no output schema, the description usefully enumerates the digest sections, giving the agent a sense of the return shape. It is essentially complete, missing only explicit return-format details, which is minor here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline of 4 applies. There is no parameter syntax to clarify, and the description correctly adds nothing that would be redundant.

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 (compute) and resource (on-demand digest of the calling user's tasks) and enumerates the digest contents (overdue, stale, new assignments, open count, recently completed). Very clear, though it does not explicitly differentiate itself from the sibling 'my_work', which appears to overlap.

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

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

Provides concrete usage context via example questions ('what needs my attention?', 'what's my work summary?'), which effectively tells the agent when to reach for this tool. It stops short of naming when-not to use it or pointing to alternatives like my_work or list_tasks.

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

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

With no annotations, the description carries the safety burden alone. It discloses the composite read shape (handoff + snapshot + tasks + activity), which is real behavioral context, but never states read-only/no-side-effects, doesn't say what happens when no handoff exists, and gives no bounds on 'top open tasks' or activity window.

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

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

Front-loads what is returned before the when-to-call triggers, and every clause carries information. The trigger list is somewhat long, but each phrasing maps to a distinct user intent rather than 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?

No output schema exists, so the description must characterize the return payload — and it does, naming all four sections. No annotations means it could say more about read-only safety and empty-handoff behavior, but for a one-parameter aggregate read it is close to sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single board_id parameter, so the schema already documents it. The description's 'for a board' adds no syntax, format, or constraint information beyond what the schema provides — 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?

Specific verb+resource ('Get the full project context for a board') with an explicit enumeration of contents: session handoff, attention snapshot with its five buckets, top open tasks, recent activity. This distinguishes it from siblings like get_digest, my_work, list_tasks, and get_board_prompt 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 concrete invocation conditions ('Call this at the START of a session') plus literal user phrasings ('continue where we left off', 'what's the state of the project'), and names the specific scenario that selects it over alternatives — a new chat after a handoff was saved. No inference required.

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?

No annotations are provided, so the description carries the full burden. 'Read' correctly conveys a safe, non-mutating operation, but nothing is said about authorization requirements, what happens when the task or board does not exist, or any limits on the result.

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 with the action front-loaded and zero filler. Every clause (verb, resource, cardinality, returned fields) earns its place.

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

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

For a two-parameter read with fully documented inputs and no output schema, the description usefully sketches the return shape. It could go further on error/permission behavior, but nothing critical to invoking it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (board_id, task_number) are documented in the schema itself. The description adds no parameter-level detail — the fields it lists are return values, not inputs — 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 ('read') and resource ('one task'), and enumerates the fields returned (description, deadline, tags, status, assignee). This is enough to distinguish it from list_tasks and search_tasks, 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?

'Use this to read one task' implies the single-task retrieval case, but there is no when-not guidance and no reference to the list_tasks/search_tasks alternatives an agent would otherwise consider.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the invitee receives a notification and must accept, and that owner/admin permission is required, but it omits what happens on duplicate invitations, whether invitations expire, what gets created, and error 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?

The definition is three short sentences and front-loads the core action, with permission details preserved at the end. 'Use this command to' is slightly redundant filler, but overall it is efficient and well-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 moderate-complexity mutation tool with rich schema coverage but no annotations and no output schema, the description covers purpose, permission, and acceptance workflow. It still leaves notable gaps around invitation lifecycle, duplicate handling, cancellation, and response 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 description coverage is 100%, so the schema already documents board_id, username, and role with enum and default details. The description adds no parameter meaning beyond that structured data, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'invite a user to a board.' The added note that the invitee 'must accept' distinguishes this from a direct-add operation like add_board_member, but it does not explicitly name the sibling tool or clarify the boundary in so many words.

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 provides a permission prerequisite ('Owner/admin only') and implies the invitation workflow, but gives no explicit when-to-use versus alternatives guidance. An agent must infer that this is for pending invitations rather than immediate membership changes.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the plaintext key is returned only once and must be stored immediately (a critical one-shot return trait) and that the caller must be an organization owner/admin. It does not mention rate limits or whether existing keys are affected.

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, then usage, then the security-critical return behavior and permission requirement. Every sentence earns its place.

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

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

With no annotations and no output schema, the description supplies the essential missing context: one-time plaintext return and the owner/admin prerequisite, matching the schema's 100% coverage. It could go further on interplay with revoke_agent_key or the not-yet-enforced scope, but is largely 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 description coverage is 100%, so the schema already documents all four parameters (including the name default and scope enum caveat). 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 and resource ("Mint a new API key for an agent member") and the target scope. It is clearly distinguishable from sibling revoke_agent_key, the inverse action, 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?

"Use for rotation or additional keys" gives clear when-to-use context. There is no explicit exclusion or direct pointer to the sibling revoke_agent_key, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden. It partially discloses the payload (active API-key counts, last key use) and an authorization requirement, which is genuine added context. It omits pagination behavior, result limits, and whether inactive/revoked keys are included.

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 and scope front-loaded and the permission constraint appended. No filler, though the return-content clause slightly crowds the opening sentence.

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

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

Absent an output schema and annotations, the description covers purpose, auth, and some return content — adequate but not complete. Missing pagination, ordering, and how the agent-account subset is shaped leaves real gaps for an agent planning the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter already documents the namespace slug, so the schema does the heavy lifting. The description only restates that the org is identified by the slug, adding no format or resolution guidance.

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 — listing organization members from a namespace slug — and adds distinguishing detail about agent accounts, API-key counts, and last key use. That detail separates it from siblings like list_board_members and list_namespaces, though it doesn't name those alternatives directly.

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?

'Requires organization owner/admin' gives a useful prerequisite, but there is no guidance on when to choose this over list_board_members or list_namespaces. Usage is only implied by the org-level scoping.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose useful traits: v1 semantics, that AGENTS.md is returned once a prompt is set, and what an empty list signifies. It omits read/write nature and permission requirements, leaving notable gaps for an annotation-free tool.

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

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

Two compact sentences with the main purpose front-loaded and an interpretive note appended. No filler, though the quoted 'AGENTS.md' detail sits somewhat awkwardly.

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 single-parameter list tool with no output schema, the description partially compensates by explaining the return shape (AGENTS.md presence, empty-list meaning) and the v1 caveat. It is largely sufficient, though it could say more about ordering or when files other than the root appear.

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?

Only one parameter (board_id) with 100% schema description coverage, so the schema already documents it fully. The description adds no syntax, format, or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List the board's named files') and adds a clarifying gloss ('the multi-file-ready prompt store'). It does not, however, distinguish itself from the related sibling get_board_prompt or explain why a listing exists separately from fetching a prompt.

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 by explaining what an empty result means ('empty list means no prompt/files yet'), which helps an agent interpret the call. It offers no explicit when-to-use or when-not-to-use guidance and never routes the agent against get_board_prompt or update_board_file.

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?

No annotations are provided, so the description carries the full burden. It discloses the returned role taxonomy (owner/admin/user), which is genuinely useful, but says nothing about read-only safety, permissions required, pagination, or ordering. Moderate but incomplete disclosure.

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

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

A single compact sentence with the action front-loaded and no filler. Appropriate size for a one-parameter list tool, though it could have added one clause of usage context within the same brevity.

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 single-parameter read tool with a fully documented schema and no output schema, the description covers the essentials and even hints at the return shape via the role enumeration. Only minor gaps (no pagination or permission notes) remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single board_id parameter, so the schema already carries full parameter documentation. The description adds no format or constraint detail beyond it, making the baseline 3 appropriate.

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

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

States a specific verb ('see') and resource ('all board members and their roles'), and enumerates the role values returned. It is clearly distinguishable from siblings like add_board_member, invite_board_member, and remove_board_member, though it does not name them 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?

'Use this command to see all board members' implies the read use case but gives no conditions, prerequisites, or alternatives (e.g., when to prefer this over list_pending_invitations or list_boards). Usage is implied rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: not the default treatment of archived boards, not pagination/limit behavior, not result ordering or shape. The archived-filter semantics in the schema are nontrivial and go unexplained.

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 wasted words. It is efficient, though its brevity reflects under-specification rather than disciplined conciseness.

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 list tool with no annotations and no output schema, the description leaves key gaps: what the return looks like, archived-board defaults, and pagination. An agent can call it, but completeness is thin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented in the schema, which sets the baseline at 3. The description adds no additional parameter meaning (no guidance on combining include_archived vs only_archived, no rationale for limit).

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 implies a board-discovery/list operation ("discover boards") but never states the core verb+resource combination explicitly the way a list tool should, nor does it note the 5 available filters. An agent can infer it lists boards, but the scope is left vague relative to siblings like get_board_by_namespace or list_board_tags.

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 one clear temporal cue: use it 'before creating or filtering tasks.' That is genuine usage context, but it names no alternative tools (e.g., get_board_by_namespace for direct lookup) and states no when-not-to-use conditions, leaving the agent to guess how to resolve a board by 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?

With no annotations, the description carries the full burden, and it discharges much of it by disclosing deduplication, casing normalization ('first-seen casing'), and sort order ('case-insensitively') — non-obvious behaviors an agent would otherwise have to infer from results. It doesn't mention pagination or whether it requires read permissions, so it stops short of a 5.

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

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

Two sentences, both front-loaded with the actionable information: the purpose/usage clause first, the return contract second. No filler or restatement of the tool name.

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

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

For a single-parameter, read-only list tool with full schema coverage, the description covers the remaining gaps — when to use it, what it returns, and how results are ordered and deduplicated, which matters given there is no output 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% and there is a single well-documented required parameter (board_id). The description adds no syntax, format, or constraint detail beyond what the schema already 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 and resource ('discover which tags already exist on a board') and goes further by specifying the return shape — unique tag strings. An agent can distinguish it from list_tasks, list_statuses, and the other list_* siblings 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 frames the use case as a prerequisite step ('before filtering with list_tasks'), naming the sibling tool that consumes the result. This tells the agent not just when to call it but why, which is the strongest form of usage guidance for a discovery 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Retrieve all' implies a read-only operation, but nothing is said about ordering, pagination, permissions, or what happens when the task has no checklist items.

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 purpose and followed by the required inputs. There is minor redundancy in restating the required parameters, but nothing 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 two-parameter read tool with complete schema coverage this is roughly sufficient, but with no output schema and no annotations the description could have described the returned checklist item shape and any ordering guarantees. It leaves those gaps 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 description coverage is 100%, so both board_id and task_number are already documented in the schema with their meanings. The description only restates that both are required, adding no format or scoping detail 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?

States a specific verb and resource ('retrieve all checklist items for a specific task'), which clearly separates it from its write siblings add_checklist_item, update_checklist_item, and delete_checklist_item. It does not name those siblings explicitly, but the read/list distinction 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?

'Use this to retrieve all checklist items for a specific task' gives the context of use, and the second sentence states the required inputs. There are no exclusions, prerequisites, or named alternatives, so usage is implied rather than fully guided.

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?

No annotations are provided, so the description carries the full behavioral burden. It never states that this is a read-only operation, whether results are paginated or ordered, or what volume/limits to expect, leaving an agent with only the word 'retrieve' to infer safety and shape.

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 purpose and with no wasted prose. The second sentence duplicates what the schema already enforces as required, so it is slightly redundant, but the overall size is appropriate for a simple list tool.

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

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

For a two-parameter, 100%-documented list tool this covers the essentials, but with no output schema and no annotations the description should have said something about the returned shape, ordering, or pagination behavior. Adequate but with a clear gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so board_id and task_number are already documented in the schema. The description's 'Provide board_id + task_number' merely restates the required parameters and adds no format, scope, or constraint detail beyond the structured fields, which is the baseline 3 case.

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 ('retrieve all comments') and bounds it to 'a specific task', which separates it from add_comment and delete_comment by verb. It does not explicitly contrast with the potentially overlapping list_task_activity sibling, so it stops short of full sibling differentiation.

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

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

'Use this to retrieve all comments for a specific task' implies the context (you have a task and want its comments) but gives no when-not guidance and does not mention the alternative of list_task_activity, which also surfaces task-level activity. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden. It usefully discloses what the returned set contains (personal + owned/member org namespaces) and that it is a discovery/read operation, but says nothing about authorization requirements, visibility edge cases, or result size.

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, zero waste. The scope definition is front-loaded and the usage cue follows immediately.

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 listing tool with no annotations and no output schema, the description supplies the essential missing piece: what the returned collection consists of. Only minor gaps (auth context, pagination/volume) remain.

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 there is nothing for the description to disambiguate. There is no parameter meaning to add or omit.

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?

Names a specific verb (list) and resource (namespaces) and immediately defines the scope of the result set: the personal namespace plus organizations the user owns or belongs to. It is unambiguous and clearly distinct from list_boards/list_agents, though there is no near-sibling to explicitly 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?

"Use this to discover where boards can be created or moved" gives a concrete when-to-use and ties the tool to create_board/move_board. It provides no explicit exclusions, but the usage 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the returned fields (substituting for the missing output schema) and the ownership scope, but says nothing about read-only nature, auth requirements, pagination, or whether revoked clients are included.

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, front-loaded with the verb+resource and finished with the payload fields. Every token earns its place with no redundancy or filler.

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

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

For a parameterless read tool with no output schema, listing the returned fields is exactly the right compensation and largely completes the picture. Missing pagination/ordering and the treatment of revoked clients are the only 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?

The tool takes zero parameters, so there is no parameter semantics to convey; baseline 4 applies. The fields listed in the description are return values, not inputs, so they add no parameter meaning but do no harm.

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+resource (list OAuth2 clients) and adds an ownership scope ("you own") plus the surfaced fields. It is clear what the tool does, but it never names the sibling create_oauth_client or revoke_oauth_client to differentiate from, so it stops short of a 5.

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

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

There is no explicit when-to-use or when-not guidance and no mention of the create_oauth_client / revoke_oauth_client siblings that share this resource. The purpose is self-evident for a list tool, but the description offers no routing help.

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

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

No annotations are provided, so the description carries the full burden. It discloses the membership precondition for the board_id mode, which is useful, but omits read-only confirmation, output/return shape, and pagination behavior for potentially long lists.

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 sentences, each covering one mode, with the default (no board_id) front-loaded. 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 single-optional-param read tool with no annotations and no output schema, the description covers both call modes and the key permission caveat. Return-format details are the only notable omission, and those are minor for a list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the board_id meaning is already fully documented in the schema, and the baseline is 3. The description reinforces the same optional/omitted semantics, adding no syntax or format detail 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?

States a specific verb and resource — listing pending invitations — and clarifies the two scopes (personal vs per-board) via board_id. It is clearly distinguishable from mutating siblings like respond_to_invitation and cancel_board_invitation, though it never names an alternative 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?

Explicitly tells the agent when to omit board_id (view personal invitations) and when to pass it (view a board's invitations). It even states a prerequisite ('must be a member'), but does not route to adjacent tools such as respond_to_invitation when action is needed.

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?

No annotations are provided, so the description carries the burden. 'Inspect' reasonably conveys a read-only, non-destructive list operation, which is useful behavioral signaling, but nothing is said about scope of results, pagination, default board fallback behavior, or permissions.

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 with no filler beyond the mildly redundant 'Use this command to' opener. The object of the action (catalog and ordering) is front-loaded and easy to scan.

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

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

For a simple single-optional-parameter list tool this is minimally adequate, but with no output schema the description could state what the catalog entries contain (status names, IDs, ordering) to help the agent use the result. The purpose is conveyed; the output is not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single board_id parameter is already fully documented in the schema ('Optional board ID. Defaults to user's active board.'). The description adds no syntax, format, or constraint detail beyond what the schema provides, 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 clear verb (inspect/list) and resource (the board status catalog and its ordering), which distinguishes it from the create_status/update_status/delete_status siblings that mutate statuses. It does not explicitly name which sibling to use instead, but the read-oriented framing 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?

The phrase 'Use this command to...' gestures at usage but gives no conditions, prerequisites, or alternatives. It never says when to pick this over update_status, reorder_statuses, or create_status, leaving routing to inference from 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?

No annotations are provided, so the description carries the full burden. It discloses the return shape ('timeline of activity entries') and implicitly the read-only nature via 'read the history', which is useful. However, it says nothing about permissions, ordering, retention, or pagination behavior.

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

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

Two tightly written sentences with zero waste; the purpose and return format are both front-loaded and nothing is redundant.

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

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

For a read-only list tool with 100% schema coverage and no output schema, the description covers the essentials: what it reads and what it returns. It could say more about the shape of an activity entry (actor, timestamp) or pagination, but nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (limit, offset, board_id, task_number) are already documented in the schema, including defaults for limit and offset. The description adds no parameter-level meaning beyond that, which matches the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'read the history of actions performed on a task', and enumerates the action types (create, update, status changes, comments). It is distinguishable from list_comments or get_task by framing itself as an audit/activity timeline, 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?

'Use this to read the history...' implies the use case but gives no when-not guidance and does not name an alternative tool (e.g., list_comments when only comments are wanted). Usage is implied rather than specified.

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

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

With no annotations, the description carries the full behavioral burden. It hints at deletion handling via 'deletion state,' but does not say whether deleted tasks are included by default, how results are ordered or paginated (only a 'limit' param exists), or whether any permission is required. For an 11-parameter read tool this leaves key behavior undisclosed.

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 that packs the full filter surface into one line with no filler. It is efficient, though the trailing enumeration is somewhat run-on.

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 list tool with rich 100% schema coverage and no output schema, the parameters are adequately covered. However, default deletion behavior, result ordering, pagination semantics, and the absence of any note on how it relates to search_tasks leave meaningful gaps for an agent choosing between siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter including aliases and date bounds. The description merely re-lists the filter categories and adds no syntax, default, or semantics beyond what the schema provides, which is the expected baseline.

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

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

States a specific verb (inspect/list) and resource (task backlog) and enumerates the filter dimensions it supports. It is clear what the tool does, but it never distinguishes itself from the closely related siblings search_tasks, my_work, and list_task_activity, which also return task collections.

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?

'Use this to inspect task backlog' frames a use case but supplies no when-to-use vs when-not guidance and never names an alternative such as search_tasks for keyword/full-text queries or my_work for the caller's own tasks. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden. It discloses a useful constraint (the 3-character code must be unique in the target namespace) and a side effect (the board URL will change), which is real behavioral value. But it omits auth/permission requirements, reversibility, and failure behavior on code collision.

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

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

Four short sentences, front-loaded with purpose and each contributing something (purpose, constraint, side effect, usage). No filler, though it is slightly more verbose than a single tight sentence 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?

For a mutation tool with no annotations and no output schema, the description covers purpose, a uniqueness constraint, a side effect, and a use case, which is reasonably complete. It still leaves gaps around permissions and what happens to related board data or on collision failure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and namespace_slug's schema already points to list_namespaces for discovery. The description adds no syntax, format, or constraint detail for the two parameters beyond what the schema provides, so baseline 3 is correct.

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

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

States a specific verb (move) and resource (board) with explicit scope: 'from its current namespace to a target namespace'. This is clearly distinguishable from siblings like transfer_board_ownership (ownership) and move_task (tasks), without needing to open a schema.

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

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

Provides a clear use case: 'Use this to consolidate boards into an organization namespace.' This gives an agent solid context for when to reach for it. However, it doesn't name alternative tools (e.g., transfer_board_ownership) or state when NOT to use it.

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

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

With no annotations, the description carries the full burden and does disclose two meaningful side effects: the task gets a new number in the target board, and status is reset to the target board's default when the current status doesn't exist there. It does not disclose what happens to the source-board number, whether comments/checklists/history carry over, or any permission requirements, which keeps it out of 5 territory.

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, zero filler, front-loaded with the action and followed immediately by the two behavioral consequences an agent needs before invoking. Every sentence earns its place.

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

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

For a three-parameter mutation tool with no annotations and no output schema, the description covers the essential behavioral surprises (renumbering, status reset). It is not fully complete — transfer semantics for related data and failure conditions (e.g., invalid target board) go unmentioned — but nothing critical is missing for a correct call.

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 task_number, source_board_id, and target_board_id are already fully documented in the schema. The description adds no syntax, format, or constraint detail beyond it, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('transfer a task between boards'), which distinguishes it from update_task (field edits), transition_task_status (status-only change), and move_board (moving a board, not a task). It never names a sibling explicitly, so it stops short of a 5, but the resource scope 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?

'Use this to transfer a task between boards' implies the context of use but names no alternative and no exclusion — an agent is left to infer that this is the cross-board move path rather than transition_task_status or update_task. Adequate but with a clear routing gap in a sibling list that contains three other task-mutating tools.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: a hard cap of 100 results, ordering by most recent update, and caller-scoped visibility. It omits whether the read requires any permission and what each task record contains, but the core operational traits are stated.

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, front-loaded with the return behavior and scope before the usage guidance. No filler; every clause conveys a distinct fact.

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 optional-param read tool with no output schema, the description covers result cap, ordering, scope, and usage adequately. It could note the shape of returned tasks, but nothing essential to correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is optional, so the schema already documents namespace_slug fully. The description adds the scoping intent, but it refers to it as 'namespaceSlug' while the schema property is 'namespace_slug', a naming mismatch that adds minor friction rather than clarity.

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 with precise scope: tasks 'assigned to or created by the caller across all boards they can access.' This is clearly distinguishable from siblings like list_tasks, search_tasks, and get_task, which are not caller-scoped.

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 concrete use cases ('what's on my plate?', surfacing overdue/stale work) that make the intended trigger obvious. It does not, however, name alternatives or state when to prefer list_tasks or search_tasks instead, so it falls short of explicit routing.

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

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

With no annotations, the description carries the full burden and delivers: it discloses the side effect of reverting a member to a regular Telegram member on group-linked boards, the no-op case for Telegram-only members, and the permission hierarchy. It doesn't cover notifications or return behavior, but the mutation's key traits are well surfaced.

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 purpose is front-loaded in the first sentence and each subsequent sentence adds a distinct constraint (revert behavior, removability, permission rules). The text is dense but every sentence earns its place; 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 two-parameter mutation with no output schema, the description covers who may call it, what happens to the target, and the failure case comprehensively. Return/confirmation behavior is not described, but the permission and side-effect picture is essentially 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 100% and both parameters (board_id, user_id) are already documented in the schema. The description adds no syntax or format meaning beyond what the schema provides, 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 opens with a specific verb+resource ('remove a member from a board') that immediately distinguishes it from siblings like add_board_member and invite_board_member. An agent can tell exactly what this 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 clearly specifies who can perform the removal (owner removes admin/user, admin removes user) and the exclusions ('Cannot remove owner'), plus the edge case that Telegram-only members cannot be removed. It lacks an explicit comparison against sibling removal/role tools, but the conditions are well 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?

With no annotations, the description carries the full behavioral burden for a mutation tool. The word 'deterministic' hints that the full set of status IDs may be required, but it never states what happens to omitted statuses, whether the change is reversible, what permissions are needed, or what the response looks like.

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 required input. No filler, though it is arguably too terse for a mutation tool.

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

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

For a mutation tool with no annotations and no output schema, the description is too thin — it omits the semantics of the reorder (must all statuses be supplied? what is dropped?), leaving an agent without enough to call it confidently.

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 both parameters are already documented in the schema, giving a baseline of 3. The description only echoes 'orderedStatusIds' and adds no format or constraint detail 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 verb 'set ... ordering' plus the resource 'status ordering for a board' clearly identifies a reorder operation on a board's statuses. It is distinguishable from siblings like create_status, update_status, and list_statuses, though it never names those siblings to sharpen the contrast.

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 says to 'provide orderedStatusIds' but gives no when-to-use context, no prerequisite that statuses must already exist, and no comparison to update_status or move_task. Usage is only faintly 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?

No annotations are provided, so the description carries the full behavioral burden. It says nothing about side effects of accepting (joining the board), whether a rejection is permanent, whether permissions or membership are required, or whether an expired/already-answered invitation errors — all material for a mutation tool.

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

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

A single, front-loaded sentence with no filler beyond the perfunctory "Use this command to" opener. It is efficiently sized, though its brevity reflects under-specification rather than tight information density.

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 tool with no annotations, no output schema, and no sibling routing, the description is too thin: an agent cannot tell what happens after acceptance, what errors to expect, or how to obtain a valid invitation_id. The schema covers parameters, but the behavioral gap remains.

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 accept=true means accept and false means reject, and that invitation_id is the invitation to respond to. The description repeats "accept or reject ... by its ID" without adding format, range, or validation semantics, so the baseline 3 applies.

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

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

The description states a specific verb pair (accept or reject) and a specific resource (a pending board invitation) keyed by ID, which is enough to distinguish it from invite_board_member, cancel_board_invitation, and list_pending_invitations. It does not explicitly name any sibling or state a boundary against them, so it falls just short of the top score.

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?

"Use this command to..." frames the situation (a pending invitation awaiting response), which implies usage, but there is no explicit when-not guidance, no mention that the invitation must exist/be pending, and no pointer to list_pending_invitations as the way to discover valid IDs.

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?

No annotations are provided, so the description carries the full behavioral burden for what is a state-mutating operation. It does not say whether this requires ownership/admin permissions, what happens to the board's tasks and members on restore, whether restoring an unarchived board errors, or whether the action is reversible.

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

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

One sentence, front-loaded with the action and its precondition, with zero filler. It is efficient, though arguably too thin for a mutation tool.

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

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

For a low-complexity single-parameter tool with full schema coverage and no output schema, the core information is present. However, with zero annotation coverage the description should at least hint at permissions or side effects, and it does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a single well-documented board_id parameter, so the baseline of 3 applies. The description adds no format, range, or sourcing detail 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 (restore/recover) and resource (a previously archived board), and the phrase 'previously archived' implicitly positions it as the inverse of archive_board. It stops short of naming that sibling explicitly, so an agent must infer the routing.

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

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

'Use this to recover a previously archived board' gives an implied precondition (the board must be archived), but names no alternative and no exclusions or error conditions. Adequate but leaves the when-to-use decision partly to inference.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it stops at the workflow hint. It does not state whether restoring an active task errors, what permissions are required, whether the restore is reversible, or what side effects occur — significant gaps for a mutation tool.

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

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

A single efficient sentence with no wasted words, and the usage instruction is front-loaded. The embedded tool/flag reference ('list_tasks onlyDeleted/includeDeleted') reads slightly compressed but remains decipherable.

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 tool with a full schema and no output schema, the description covers the prerequisite workflow but omits error behavior and permission requirements. It is minimally adequate rather than 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 description coverage is 100% for both parameters, so board_id and task_number are already documented as scoped to a deleted task. The description adds no syntax, format, or lookup details beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource (recover deleted tasks), so the operation is unambiguous and distinguishable from delete_task and restore_board. It does not explicitly frame itself against those siblings, but the wording is clear enough to select correctly.

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 names the companion workflow: use list_tasks with onlyDeleted/includeDeleted to locate the task before restoring. That gives a concrete precondition for use, though it offers no when-not-to-use guidance (e.g., what to do with an already-active 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?

With no annotations, the description carries the full burden and does add real value: it discloses the authorization requirement (org owner/admin) and the eligibility constraint (agent-owned keys only). It does not state irreversibility or the immediate effect on the key, which is a meaningful omission for a destructive operation.

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 lookup key, then scope and auth. 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 destructive mutation with no annotations and no output schema, the description covers action, lookup, eligibility, and auth. Missing only the consequence (immediate invalidation / irreversibility), which would complete the picture.

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?

Only one parameter with 100% schema description coverage ('API key id (from list output or the web UI)'). The description's 'by id' merely restates the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Revoke an agent's API key') with the lookup key ('by id'), clearly distinguishing it from issue_agent_key and revoke_oauth_client. An agent can identify what this 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?

Explicitly scopes when it applies (only keys owned by agent accounts; humans revoke their own) and adds a precondition (organization owner/admin of an org the agent belongs to). It lacks an explicit pointer to an alternative tool for the human-owned-key case, so it falls short of a full 5.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the key side effect ('existing tokens are not deleted but no new authorizations will be allowed'), but says nothing about permission/auth requirements, reversibility, or the response, so coverage is partial.

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 the action and followed by the non-obvious consequence. No filler and nothing 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 simple single-parameter mutation with 100% schema coverage and no output schema, the description covers purpose and the important token/authorization behavior. Only usage guidance and permission prerequisites are absent, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single client_id parameter, so the schema already documents it fully. The phrase 'by its numeric ID' mirrors the schema and adds no meaning beyond it, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Revoke one of your OAuth2 clients') and scopes it to a numeric ID, making it immediately distinguishable from create_oauth_client and list_oauth_clients by verb 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?

There is no when-to-use guidance, no named alternative (e.g., list_oauth_clients to obtain the ID, or revoke_agent_key), and no stated prerequisites. The reader can infer the operation but is given no routing or context for choosing 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?

With no annotations the description carries the full load, and it does disclose the durable-note nature, the content structure it captures, and a genuine authoring constraint (summary must be your own recap, not a transcript). It stays silent on permissions, whether repeated calls overwrite prior handoffs, and side effects, leaving gaps for a mutation tool.

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

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

Front-loads the core purpose and stays to three tight sentences. Slight redundancy with the schema on the summary/transcript point keeps it from being fully waste-free.

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-param write tool with full schema coverage and no output schema, the description covers purpose, timing, and content well. Remaining gaps (return value, permission needs, idempotency) are minor but real.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already documents summary and links in detail, so the baseline is 3. The description largely restates the schema's guidance (authored recap, PR/issue/branch links) rather than adding new syntax or format meaning.

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

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

States a specific verb (save) and resource (session handoff / durable note on the board), and enumerates exactly what it records: done, next, blocked, and links. An agent can cleanly separate it from generic siblings like add_comment or create_task.

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 strong positive timing cues ('Call this at the END of a working session') plus concrete trigger phrases ('remember where we left off', 'save our progress'). It does not name an explicit alternative or a when-not condition, so it falls just short of the 5 bar.

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

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

With no annotations, the description carries the full behavioral burden, and it does add real value beyond the schema: the 50-result cap, the 'ordered by last updated' sort, and the cross-board scope. It still omits whether archived tasks are included, relevance vs. recency ranking, and any read-only/auth guarantees.

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

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

Three tight sentences: purpose and scope first, then the optionality/combinability rule, then the return contract. No filler, and the most decision-relevant information is front-loaded.

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

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

There is no output schema, so the description rightly states the return shape (up to 50, ordered by last updated), and it covers scope and filter behavior. Only minor gaps remain, such as archived-task visibility and ranking semantics, but an agent can call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description adds only the combination hint ('combine them to narrow results') and notably omits board_id from its filter 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 clear verb+resource ('find tasks') and enumerates the exact filter dimensions plus the scope ('across all your accessible boards'). It does not differentiate itself from siblings like list_tasks or my_work, which also return tasks, so an agent must infer the boundary.

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

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

'Use this to find tasks... All filters are optional — combine them to narrow results' implies the usage context of a filtered lookup. However, it never states when to prefer this over list_tasks, get_task, or my_work, leaving the routing decision to inference.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses server-side type coercion and the accepted boolean string forms (on/off, true/false, 1/0, yes/no), which is real behavioral detail. However, it omits permissions/auth requirements, error behavior for unknown keys, and whether changes are reversible.

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

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

Four short sentences, front-loaded with the purpose, followed by coercion rules, a discovery pointer, and a concrete example. Efficient with minimal waste, though the example sentence is somewhat verbose.

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 mutation tool with no annotations and no output schema, the description covers purpose, coercion semantics, and how to discover valid keys. It leaves out permissions and failure modes, but the discovery pointer and coercion details make it largely complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds some value by elaborating on coercion and adding 'yes/no' to the boolean formats, but the schema already covers most of this. 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 ('change') and resource ('a board setting'), clearly distinguishable from siblings like update_board, get_board_settings, and get_board_settings_schema. 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?

The description names get_board_settings_schema as the way to discover available keys and types, which is explicit routing guidance. It does not state when NOT to use it or contrast with update_board, but the usage 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?

With no annotations, the description carries the full burden and delivers: it discloses the demotion side effect on the current owner, the default role, the permission requirement, the target precondition, and flags irreversibility ('irreversible high-impact operation'). This is exactly the behavioral context annotations would otherwise supply.

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

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

Front-loads the core action, then layers preconditions and the irreversibility warning in tight, waste-free sentences. No filler or redundancy despite covering several distinct facts.

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 high-impact mutation with no annotations and no output schema, the description covers prerequisites, side effects, defaults, and irreversibility. Nothing an agent needs before calling is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (including the demote enum and its 'admin' default) are already fully documented. The description restates the demotion default and target-membership rule but adds no syntax, format, or meaning beyond the schema. 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 ('Transfer ownership of a board') plus the exact source and target actors. It is clearly distinguishable from sibling member tools like update_member_role, add_board_member, and invite_board_member.

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

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

Gives explicit preconditions ('Only the current board owner can initiate a transfer'), a constraint on the target ('must already be a board member'), and names the corrective alternative ('invite them first if needed'). An agent has everything needed to decide whether and how to call it.

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

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

No annotations exist, so the description carries the full behavioral burden. It discloses one useful trait — that other fields are left untouched — but says nothing about permission requirements, whether the target status must already exist, whether transitions are validated or restricted, or any side effects (activity log, notifications).

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 that front-loads the usage cue and states the partial-update constraint without waste. It is efficient, though its brevity comes at the cost of the behavioral detail the tool lacks elsewhere.

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 three required parameters, no annotations, and no output schema, the description should explain valid status values, existence requirements, and side effects. Instead it provides one clause, leaving an agent unable to predict failure modes or return behavior for a mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (task_number, board_id, status) are already documented in the schema. The description adds only the implicit notion that status is the sole mutated field; it contributes no format, validation, or lookup guidance 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 gestures at a mutation of a task's status ("explicit status moves") but never names the resource or states a concrete verb like "set" or "transition". An agent must infer the target object from the tool name alone, and nothing separates it from update_task or move_task.

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?

"Use this for explicit status moves while keeping other fields unchanged" implies the selection condition (change only the status) but never names the competing siblings update_task or move_task, and gives no exclusions or prerequisites. Usage is inferable but not spelled out.

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

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

With no annotations, the description carries full load. It usefully discloses partial-update semantics and the empty-string-clears-prompt behavior, but omits permission requirements (owner/admin) and error behavior for a mutation tool; it also repeats the 'omit to leave unchanged' rule already present in every schema property.

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

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

Three tight sentences, front-loaded with the action and fields, then the patch rule, then the edge case. Nothing is padded and each sentence earns its place.

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

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

For a mutation tool with no output schema and fully documented parameters, the description covers the essentials: what changes, patch semantics, and prompt clearing. It would be complete with a note on permissions (visibility is owner/admin only), which it omits.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds the AGENTS.md location and clearing semantics for prompt, but says nothing about visibility, which the schema alone documents; value beyond the schema is marginal.

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 (edit) and resource (board metadata: title, code) plus the board-level agent prompt, so an agent knows this mutates board attributes. It does not explicitly distinguish itself from the sibling set_board_setting or get_board_prompt, leaving sibling routing to inference.

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

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

The patch semantics ('pass only the fields you want to change; omitted fields are left untouched') is good operational guidance, but there is no explicit when-to-use versus alternatives like set_board_setting, nor any stated preconditions. Usage is implied rather than framed.

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

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

With no annotations, the description carries the full burden and does disclose several behavioral traits: upsert semantics, the clear-on-empty behavior, and the v1 single-file limitation. It omits permissions/auth requirements and return behavior, which keeps it from a 5 for a mutation tool.

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

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

Front-loaded with the core action, then the clearing rule and versioning caveat. The future-versions sentence is slightly speculative but is short and helps set expectations; overall tight with minimal waste.

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

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

For a write tool with no annotations and no output schema, the description covers purpose, clearing semantics, and version scope. What remains missing (return shape, overwrite/conflict behavior, permissions) are gaps but not disqualifying; the schema already handles argument documentation.

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 all four parameters are already documented in the schema. The description's only parameter-relevant detail (omit/empty content clears the body, AGENTS.md as conventional name) is already repeated in the schema descriptions, adding no new meaning. 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: 'Upsert a named markdown file on a board.' It goes further to position itself against a sibling, naming update_board's prompt option as the higher-level path, so an agent can distinguish it without opening schemas.

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

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

It gives a clear usage rule ('Omit content (or pass empty) to clear a file's body') and a routing hint ('low-level writer beneath update_board's prompt option'), which implies when to prefer the sibling. It stops short of an explicit when-not-to-use-this instruction, so it falls just short of 5.

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

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

With no annotations provided, the description carries the full behavioral burden. It says 'update' (a mutation) but does not disclose whether the update is partial or full replacement, what happens if item_id doesn't exist, whether permissions are required, or what the response looks like. For a mutation tool with zero annotation coverage this is a significant gap.

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 required input. Efficient, though the second sentence is largely redundant with the schema and could have carried behavioral detail instead.

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?

Parameters are fully covered by the schema and the purpose is clear, but for an unannotated mutation tool with no output schema the description is thin on behavior: no auth/permission context, no error semantics, and no confirmation of partial-update behavior. Minimum viable rather than 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 description coverage is 100%, so the schema already documents item_id, title, and done. The description only restates 'Provide item_id and fields to update,' adding no syntax, format, or constraint detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb ('update') and resource ('checklist item'), plus the exact fields affected (title, done status). This distinguishes it from add_checklist_item, delete_checklist_item, and list_checklist without naming them, so it is clear but short of explicit sibling differentiation.

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

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

The opening 'Use this to update...' implies when the tool applies, but there is no explicit when-not guidance and no named alternative (e.g., delete_checklist_item for removal, add_checklist_item for creation). Usage is inferable from the purpose rather than stated.

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

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

With no annotations, the description carries the full burden and does supply the authorization requirement (owner/admin only) plus two hard guardrails (no targeting the owner, no promoting to owner). It omits what happens on a rejected call, whether the change is audited/notified, and whether it is idempotent.

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, zero filler, with the action front-loaded and the constraints following immediately. Every sentence earns its place.

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

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

For a 3-param mutation tool with no annotations and no output schema, the description covers purpose, permission gate, and the two most dangerous edge cases. It is nearly complete; only failure/idempotency 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 description coverage is 100%, so the schema already documents board_id, user_id, and the role enum. The description reinforces the role restriction ("cannot promote anyone to owner") but adds no syntax, format, or lookup guidance beyond what the schema states; baseline 3 applies.

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

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

The description states a specific verb and resource ("change an existing board member's role") with the scope qualifier "existing" that separates it from add_board_member/remove_board_member/invite_board_member. An agent can identify this as the role-mutation tool 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 preconditions and exclusions: owner/admin only, cannot target the board owner, cannot promote to owner. It does not name a sibling alternative (e.g. use add_board_member to invite, transfer_board_ownership for ownership changes), so it falls short of explicit when-not/alternative routing.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does not state whether this is a partial or full update, what permissions are required, whether fields not supplied are preserved, or how conflicts/unknown status IDs are handled for a mutation tool.

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

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

A single sentence with no filler, and the core action is front-loaded. It is arguably terse enough to leave gaps, but there is no wasted structure to trim.

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 no annotations and no output schema, the description is thin: it omits which fields are updatable, whether the update is partial, and constraints on the identifier modes. An agent must infer most calling behavior from the 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 100%, so the baseline is 3, but the description adds genuinely new semantics: status_id and board_id+code are alternative lookup mechanisms, a relationship the schema does not express. It still does not clarify whether exactly one mode is required.

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 clear verb ('Update') and resource ('status'), and clarifies the two identity-resolution paths. It does not explicitly distinguish itself from siblings like create_status or delete_status, but the verb makes the CRUD 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 description explains the two ways to address a status (statusId vs boardId+code) but gives no when-to-use guidance, prerequisites, or mention of alternative tools such as reorder_statuses or transition_task_status. 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?

No annotations, so the description carries the full behavioral burden and falls short. It implies a mutation but does not disclose partial-vs-full update semantics (e.g., whether omitted fields are preserved), permission requirements, or reversibility. For a 9-parameter mutation tool this is a significant gap.

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 wasted words. However, it is so terse that it sacrifices useful content, and the 'Use this to' preamble adds no 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?

A mutation tool with no annotations and no output schema, yet the description says nothing about return values, partial-update behavior, or error conditions. Given the complexity of 9 parameters, this is under-specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter, including replace semantics for tags and the assignee username format. The description's field list adds little beyond the schema and even omits priority. 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 clear verb (edit) and resource (task) and enumerates the editable fields. It distinguishes itself implicitly from create_task/delete_task/move_task, but never names those siblings or clarifies the overlap with transition_task_status. Also omits the priority field that exists in 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?

No when-to-use or when-not-to-use guidance. Notably, the description claims it edits status, which overlaps with the sibling transition_task_status, yet no routing rule is given. No prerequisites or preconditions mentioned.

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