Kangram

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

Adds real context beyond the annotations: immediate effect, owner/admin-only authorization requirement, and that the owner role cannot be created or assigned. Annotations already cover safety/idempotency, but the description leaves the non-idempotent behavior (what happens when the user is already a member) 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?

Three short sentences, front-loaded with the core action, with the authorization caveat last. Slight redundancy between 'Owner/admin only' and 'cannot create or assign the owner role', which the schema also states.

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?

Covers what the tool does, the authorization gate, and the role ceiling, which is enough for a simple three-parameter mutation with no output schema. The only gap is behavior when the target is already a member, which matters given idempotentHint=false.

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 three parameters including the role enum and the 'cannot assign owner role' constraint are already documented. The description echoes the owner-role restriction but adds no new format or usage detail 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 and resource ('add a user directly to a board') and immediately clarifies the semantics: immediate membership with no invitation to accept, which cleanly separates it from invite_board_member in the sibling list.

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

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

Explains the selecting condition (direct, one-step grant) and implicitly excludes the invitation flow by noting there is nothing to accept. It would be stronger if it named invite_board_member explicitly as the alternative for invited members.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond that: it does not say that repeated calls create duplicate items (non-idempotent), whether ordering is appended, or whether the board/task must exist or be writable.

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 purpose front-loaded and no filler. The lead-in 'Use this to' is slightly redundant given the name but not wasteful enough to penalize further.

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

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

For a simple 3-parameter mutation with full schema coverage and annotations, the description covers the essentials of what to call and how to target the task. It omits any mention of the created item being returned or duplicate guards, which would round it out.

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

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

Schema description coverage is 100%, so title, board_id and task_number are already documented. The description reinforces that board_id + task_number jointly identify the task, which is mildly useful but adds little beyond the schema baseline.

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

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

The description uses a specific verb and resource ('add a new item to a task's checklist'), which is clearly distinct from siblings like add_comment or update_checklist_item. It does not explicitly name or contrast with those siblings, keeping it below 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?

'Use this to add...' implies the usage context, and it says how to identify the task. However, it gives no guidance on when to prefer update_checklist_item vs delete_checklist_item, nor any prerequisites such as required permissions on the board.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the write/safe profile is covered. The description adds nothing beyond those hints: it does not say whether duplicate comments are allowed, what permission is needed, or what the call returns, despite non-idempotent creation being exactly the case where that matters.

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 the identification requirement second. The second sentence largely restates what the schema already says about board_id and task_number, so it is useful but not fully 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?

No output schema exists, yet the description never indicates what is returned after a comment is created (e.g., new comment id), which matters for a non-idempotent create. Otherwise it is sufficient for a simple three-parameter tool backed by complete schema descriptions and annotations.

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 params are documented in structured data and a 3 is the baseline. The description contributes only the relational hint that board_id + task_number jointly identify the task, which is mild 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 concrete verb and resource ('add a comment to a specific task'), which is clearly distinct from delete_comment and list_comments. It stops short of naming those siblings explicitly, so an agent must infer the boundary rather than being told.

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

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

Usage is implied by 'Use this to add a comment to a specific task' plus identification guidance for the target task. There is no statement of when not to use it, no prerequisites (e.g., membership on the board), and no reference to the competing tools (delete_comment, list_comments).

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?

Goes well beyond the annotations: discloses that access is inherited immediately, that explicit board membership overrides, that the member may create/move boards into the namespace, that 'owner' is structural and unassignable, and that the caller must be the workspace owner. These are non-obvious authorization and side-effect facts the agent could not infer from readOnlyHint=false / destructiveHint=false.

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

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

Front-loaded with the core action and scope, then layers on inheritance, roles, and auth in dense, non-redundant sentences. The role sentence slightly overlaps the schema description, but nothing is padding.

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

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

For a non-idempotent mutation with no output schema, it covers authorization, side effects, and role constraints well. It does not say what happens if the user is already a member (relevant given idempotentHint=false) or how failures are reported, leaving one meaningful gap.

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

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

Schema coverage is 100%, so the schema already documents slug format, username case-insensitivity, and the role enum. The description's role text ('owner' is structural and cannot be assigned) and 'existing user' largely restate the schema rather than adding new meaning, so it sits at the high-coverage 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 and resource — 'Grant an existing user workspace-level membership (NamespaceMember row) in the namespace identified by its slug' — and distinguishes itself from sibling tools by emphasizing 'existing user' and 'Direct grant — no invitation to accept', which separates it from invite_board_member and add_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?

It establishes the precondition ('Requires the workspace owner'), the eligibility ('an existing user'), and rules out the invitation flow ('Direct grant — no invitation to accept'). It never names invite_board_member or add_board_member explicitly as the alternative for the other cases, so routing is implied rather than 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?

Annotations already declare it is not read-only, not destructive, and not idempotent. The description reinforces the non-destructive nature ('without deleting it'), which adds real value, but it says nothing about reversibility, whether data/tasks are retained, or what happens if the board is already archived — notable given idempotentHint=false.

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

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

One short sentence, front-loaded with the intent and ending with the key constraint. Zero 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 one-parameter mutation with annotations covering the safety profile, the description gives enough to act correctly. Remaining gaps — reversibility and already-archived behavior — are minor but real for a non-idempotent mutation.

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

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

There is a single required parameter with 100% schema description coverage ('Board ID to archive'), so the schema fully documents it. The tool description adds no syntax, format, or sourcing guidance beyond that, which is the expected baseline when the schema does the work.

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

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

The description states the concrete effect of the operation (hiding a board from active workflows) and implicitly contrasts it with deletion, which is more informative than restating the name. It never explicitly uses the verb 'archive' or names a board identifier, but the name and title carry that. It is clear enough to distinguish from siblings like delete_task or update_board.

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 'without deleting it' implies the when-to-use condition relative to destructive alternatives, but no sibling (restore_board, update_board, move_board) is named and there are no explicit exclusions or prerequisites. Usage is inferable but not stated.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. Beyond that, the description adds genuinely useful behavior: a 10MB decoded size ceiling, where the attachment surfaces afterward (web task view, list_task_files), and the permission requirement. It does not mention whether repeat uploads create duplicates or how failures are reported, which keeps it short of a 5.

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

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

Four short sentences with zero filler, front-loaded with purpose, then constraint, then effect, then intended use case. Every sentence contributes a fact an agent needs to call the tool correctly.

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 output schema, the description covers the essential gaps: size limit, encoding format, permission prerequisite, and observability of the result. Annotations carry the safety profile and the schema carries all six parameters, so nothing material is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description contributes meaning the schema lacks: the 10MB decoded limit on content_base64 and the "no data: prefix" encoding contract, both of which prevent common invocation errors. It does not clarify the upload_type category semantics, leaving that parameter's purpose thinner.

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

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

The description opens with a specific verb and resource ("Attach a file to a board task") and immediately clarifies the mechanism (base64 content) and downstream visibility. It implicitly distinguishes itself from siblings such as list_task_files and list_board_files, which are read operations, so an agent can tell what this tool is for without opening 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?

It gives clear context for when to use it ("artifacts an agent produces or handles: images, documents, exports") and a hard prerequisite (board membership). What is missing is an explicit when-not or a pointer to an alternative path for files that exceed the limit, so the guidance is strong 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?

Beyond the annotations, it discloses the hidden side effect that the previous binding is unbound first, the post-condition that the board becomes the group's primary board, and the authorization requirement (owner/admin). Those are exactly the traits an agent cannot infer from readOnlyHint=false / destructiveHint=false, and they serve as a useful warning even though the unbinding is not flagged destructive.

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 action and its effect, followed by the prerequisite and trigger phrasing; four sentences with little waste. The closing boardRef sentence is somewhat redundant with the schema and could be trimmed.

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 an output schema absent but a self-evident result, the description covers effect, precedence (previous binding removed), authorization, and reference formats. Error behavior and return value are the only minor omissions, and the latter is low-stakes 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?

Schema coverage is 100%, so both parameters are already fully documented. The description's boardRef sentence largely restates the schema (only adding a concrete full-URL example), and it says nothing extra about group_chat_id auto-detection beyond what the schema already states, so the baseline 3 applies.

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

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

The description names a specific verb and resource (bind/link a board to a group chat) and states the resulting state change: the board becomes the group's primary board and bot commands act on it. That effect distinguishes it from move_board, update_board, and other board 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?

It gives explicit trigger intents ("when a user asks to set, link, bind, or assign a board to a chat/group") and a prerequisite (actor must be an owner/admin of the board). It stops short of naming alternatives or when-not-to-use cases, but the positive routing is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds useful authorization context (only the original inviter or a board admin), but says nothing about irreversibility, what happens to the invitee, or error behaviour when the caller lacks permission.

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 core action front-loaded and the permission caveat immediately after. Nothing 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 one-parameter mutation with rich annotations and a fully described schema, the definition covers the action and the permission gate. A note on irreversibility or on where to get invitation_id would make it fully self-sufficient, 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?

There is a single parameter with 100% schema description coverage ('Invitation ID to cancel'), so the schema carries the semantics. The description adds no format, sourcing, or lookup guidance (e.g. obtainable via list_pending_invitations), which is the baseline-3 outcome for high coverage.

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

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

States a specific verb and resource ('cancel a pending board invitation'), with 'pending' narrowing the scope so an agent won't confuse it with revoking a membership or responding to an invitation. It does not explicitly name the neighbouring alternatives, but the action 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 description gives a clear trigger condition (a pending invitation exists and should be withdrawn) and an authorization constraint. However, it never contrasts with siblings such as respond_to_invitation or remove_board_member, so the agent must infer which tool applies.

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

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

Adds substantive context beyond annotations: exactly which fields are copied vs excluded, that the caller becomes owner, that the board lands in the caller's personal namespace with a fresh code, and that authorization is enforced imperatively in execute. Annotations already flag it as non-read-only/non-destructive, and the description enriches rather than contradicts them.

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

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

Dense, front-loaded sentences with zero filler: what is copied, what is excluded, ownership, namespace placement, and authorization all stated compactly. Every sentence carries distinct information.

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

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

For a non-idempotent clone with no output schema, the description covers the full behavioral picture an agent needs: copy semantics, exclusions, ownership/namespace outcome, and authorization requirements. Nothing material is missing.

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

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

Schema coverage is 100%, so code, title, and source_board_id are all documented in the schema including the auto-generate and default-title behavior. The description's mention of 'fresh unique code' and namespace is consistent but not additive beyond the schema, 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 (clone) and resource (board), and immediately distinguishes itself from create_board by specifying what is copied (statuses, board files/prompt, title) versus excluded (tasks, comments, members). The agent can tell exactly what this does differently from a plain board creation.

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?

Clear about the scope of the operation and its eligibility conditions (read access, public boards forkable by anyone), which implicitly answers 'when can I use this'. However, it never explicitly names the alternative create_board for building a fresh board or states when cloning would be inappropriate, so it stops short of full when/when-not 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?

Goes well beyond what the annotations declare: the agent cannot log in, gets no personal namespace, becomes an org member immediately with board access via role inheritance, and requires org owner/admin. Critically, it discloses that the plainKey is returned once and never shown again, which is exactly the kind of operational detail an agent must know 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 short sentences, each carrying distinct information: what is created, its immediately observable state, the one-time key disclosure, and the authorization prerequisite. The most time-sensitive fact (plainKey shown once) is front-loaded before the tail requirement clause.

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

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

There is no output schema, so the description carries the return-value burden, and it does disclose the key field (plainKey) plus its one-time nature. It does not describe the rest of the response (e.g., the created agent's id/username) or failure cases such as duplicate username/namespace, so a small gap remains 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 the schema already documents all four parameters (role enum semantics, username constraints, display_name default, namespace_slug format). The description only restates that the org is identified by namespace slug, adding no per-parameter 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?

The description states a specific verb and resource ('Create a non-human agent account') and immediately qualifies the account type ('User type=\'agent\''), which cleanly separates it from create_organization, add_namespace_member, and issue_agent_key in the sibling list. An agent can identify exactly what this tool produces 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?

Usage context is clear: it is for non-human agent accounts inside an existing org, requires owner/admin, and auto-issues the first API key (implicitly distinct from issue_agent_key for later keys). It lacks explicit 'when not to use' guidance or a direct name-check against issue_agent_key/add_namespace_member, which keeps it at 4 rather than 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?

Annotations already declare this is a non-readonly, non-destructive, non-idempotent closed-world mutation. The description adds useful context that a default status workflow is created alongside the board, but does not explain authentication, namespace defaults, or failure behavior.

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

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

It is a single front-loaded sentence with no extraneous detail. The phrase 'Use this command to' is slightly boilerplate, but the sentence remains 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?

The description covers the main creation effect and the default status workflow, while the schema covers optional parameters. However, for a creation tool with no output schema, it does not say what is returned or clarify how defaults like namespace and group chat are resolved.

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

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

With 100% schema description coverage, the schema already documents all four optional parameters, including the namespace_slug guidance to use list_namespaces. The description adds no parameter-specific meaning beyond 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?

The description gives a clear verb and resource: initialize a board, plus the notable side effect of creating its default status workflow. It does not explicitly distinguish this from siblings like clone_board or update_board, but the create intent 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?

The sentence only restates that this command is used to initialize a board. It gives no conditions for when to use it versus clone_board, update_board, or other create tools, and no prerequisites or exclusions.

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

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

Annotations already declare a non-read-only, non-idempotent, non-destructive write, and the description adds the details that actually matter: the client_secret is returned and shown ONCE, must be stored securely, and the operation is restricted to owners. That is real behavioral value beyond the annotation set.

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 filler, with the purpose and the one-time secret warning both front-loaded before the access restriction.

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?

Despite having no output schema, the description names the returned fields (client_id, client_secret) and their one-time nature, and the owner-only constraint closes the remaining gap. An agent has everything needed to call it and handle the response safely.

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 explains name, scopes with defaults, and redirect_uri constraints (https, no wildcards). The description adds no parameter-level meaning, 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 ('Register a new OAuth2 client') plus the concrete outcome ('third-party app can authenticate users via Login with Kangram'), which clearly separates it from 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 framing 'so a third-party app can authenticate users' tells an agent exactly when this tool applies, and 'Owner-only' states a precondition. It stops short of naming the sibling tools or the when-not case (e.g., use update/revoke for existing clients), so it lands just below the top.

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

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

Annotations already flag this as a non-read-only, non-idempotent, non-destructive write. The description adds substantive context beyond that: the new org gets its own namespace, the slug is derived from the name, and the caller is granted ownership. It stops short of covering slug collisions, permission requirements, or failure modes, which keeps it from 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 with zero filler: effect, resulting state, then routing condition. The most decision-relevant content (what it creates and who owns it) is front-loaded.

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

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

For a single-parameter creation tool with no output schema, the description covers what is created and its ownership/namespace consequences. A brief note on what the call returns (org id or slug) and whether the creator needs existing permission to create an org would make it 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 the name parameter is fully documented in the schema, so the baseline is 3. The description adds real meaning by explaining that the slug is derived from the name, which tells the agent the name has naming-system consequences beyond a display label.

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 new organization') and immediately clarifies the resulting side effects: a dedicated namespace with a slug derived from the name, and the creator becoming owner. The synonym mapping (namespace/organization/workspace) resolves any ambiguity with namespace-related siblings such as list_namespaces.

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 an explicit trigger condition ('Use this when a user asks to create a namespace, organization, or workspace'), which is exactly the phrasing an agent will encounter. It does not state when NOT to use it, but there is no competing create-namespace sibling to exclude, so the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is known. The description adds no behavioral context beyond that: nothing about whether status names must be unique, what happens on duplicate name, where the status is placed in the workflow if index is omitted, or whether board_id defaults apply.

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 its brevity borders on under-specification rather than tightness.

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 five parameters, an agent still lacks confirmation about duplicate handling, workflow placement defaults, and required permissions. The rich schema and existing annotations cover structure and safety, but the description leaves the behavioral side largely blank.

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 5 params, so code derivation, color format, index ordering, and board_id defaulting are all already documented in the schema. The description contributes nothing additional about parameter behavior, 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 ("add new statuses") and names the domain object ("board workflow"), so the agent knows this creates a status rather than listing, updating, or deleting one. It does not explicitly distinguish itself from siblings like update_status or reorder_statuses, but the create semantics are 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 sentence only restates the purpose ("use this command to add new statuses"); it gives no when-to-use conditions, no prerequisites (e.g., board membership/permissions), and no mention of alternatives such as using list_statuses first to avoid duplicates. The only useful hint is that statuses belong to the board workflow.

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

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

Annotations already declare that this is a non-read-only, non-idempotent, non-destructive, closed-world write, so the safety profile is covered. The description adds one genuinely new behavioral fact — that omitting the board falls back to the caller's active board — but says nothing about permission requirements, whether the assignee is notified, or what happens if the active board is missing. Note the description writes 'boardId' while the schema parameter is 'board_id', a minor naming mismatch rather than an annotation contradiction.

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 immediately followed by the routing rule; nothing is padded. The opening 'Use this to add a task' is slightly redundant with the tool name, keeping 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?

For an 11-parameter create tool with no output schema, the description is thin: it explains board routing but not subtask creation (parent_task_number/parent_board_id), status/priority behavior, assignee format, or what a successful call returns. Annotations carry the safety profile and the schema carries parameter details, so it is adequate, but the highest-risk behaviors are left to 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?

With 100% schema description coverage the baseline is 3, and the description exceeds it by documenting the default/routing semantics of the board parameter, which the schema only describes as 'Board ID where the task should be created.' It does not touch the other ten parameters, notably subtask creation via parent_task_number, so it does not earn a 5.

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

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

The description gives a specific verb+resource ('add a task'), which cleanly separates it from update_task and delete_task among the siblings. It stops short of naming an alternative or stating scope (e.g., single task per call, required title), so it is clear but not fully differentiating.

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?

'Provide boardId for deterministic routing; otherwise active board is used' tells the agent how to pick a board, which is real usage guidance for the most consequential parameter. However, there is no guidance on when to use this versus related tools (create_board, add_checklist_item, update_task) and no preconditions or exclusions.

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

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

Annotations only flag destructiveHint=true; the description goes well beyond by naming exactly what is destroyed, the irreversible cascade, and the important fallback path where history rows block the hard delete and the agent is deactivated with row retained and status='deactivated' returned. That fallback is a critical non-obvious behavior an agent must handle.

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

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

Three dense sentences, front-loaded with the action and cascade, then the fallback, then the permission requirement. Nothing is redundant or padded.

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

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

No output schema exists, but the description supplies the one return value that matters (status='deactivated'), plus permissions and destructive scope. An agent has everything needed to call this safely and interpret the result.

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 both parameters self-documented, so the schema carries the load. The description adds no format, casing, or lookup hints for agent_username or namespace_slug, 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?

Precise verb+resource: 'Delete an agent account', with an enumerated cascade (API keys, memberships, task assignments, hard delete). It is clearly distinct from siblings like revoke_agent_key or list_agents, which a reader can infer 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 a clear precondition (organization owner/admin) and the conditional outcome that determines whether the caller gets a true delete or a deactivation. It does not explicitly say 'use revoke_agent_key instead if you only want to kill credentials', so no true when-not guidance, but the context is strong.

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

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

The tool is destructive, which is captured by the 'destructiveHint: true' annotation. The description adds no additional behavioral context, limitations, or error handling information beyond the structured data provided.

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 highly concise. Both sentences are necessary, efficient, and front-load the primary action and required input.

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

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

Given the simplicity of the 1-parameter schema and the presence of a destructive hint in the annotations, the description is sufficiently complete for an agent to understand how to invoke it without risk of serious 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?

Since schema description coverage is 100%, the schema already defines the purpose and type of the `item_id` parameter. The description adds no semantic value beyond reiterating the parameter's required function, meeting the baseline score for high schema coverage.

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

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

The description clearly states the function ('remove a checklist item from a task'). While it does not explicitly name competing sibling tools like a sibling tool comparison would, the action is unambiguous and distinct from broader organizational 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?

It provides a direct operational instruction ('Provide item_id') but offers little guidance on the lifecycle of a checklist item or when to use this deletion tool versus an update tool for modification.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered; the description adds real value beyond them by spelling out the authorization rule (author or board admin). It stops short of saying whether the deletion is permanent or what error results from an unauthorized or repeat call.

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. The opening clause slightly echoes the tool name/title, which is the only 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 destructive three-parameter tool with full schema coverage and annotation-declared safety hints, the description covers action, authorization, and required inputs. It omits irreversibility and post-delete response behavior, which would be the last piece for a 5.

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 already documented, and the baseline is 3. The description only restates the parameter names ('Provide board_id + task_number for context and comment_id') without adding format or scoping 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 description states a specific verb and resource ('delete a comment'), which cleanly separates it from add_comment, list_comments, and update_task-style siblings. It does not explicitly name an alternative, but the operation itself is unambiguous.

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

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

It gives a concrete applicability condition that an agent must check before calling: only the comment author or a board admin/owner may delete. It doesn't state when-not-to-use or point at alternatives (e.g., leaving a comment instead of deleting), 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?

Annotations already declare destructiveHint=true, but the description adds genuinely non-obvious behavior: deletion can fail or require a fallback when tasks reference the status. It still omits whether deletion is irreversible, what happens to task history, and whether permissions are required.

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 key modes; nothing is padded. The telegrammatic phrasing ("Delete by statusId or boardId+code") is efficient but sacrifices a little readability.

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?

Covers the destructive precondition that matters most, and the schema fully documents the four parameters. For a destructive, non-idempotent tool with no output schema, it leaves unclear what a successful call returns and whether the status must be empty or unused.

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 per-field meanings are already documented. The description adds real value by revealing the two mutually exclusive lookup modes (status_id alone versus board_id+code together) and the conditional role of replacement_status_id, which the schema lists only as independent properties.

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 by statusId or boardId+code") and names the lookup keys, which separates it from sibling delete_task/delete_agent and from update_status. It never explicitly contrasts with those siblings, 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?

"If tasks use it, provide replacementStatusId" gives one real conditional rule for using a parameter, which is more than most tools offer. However, it says nothing about when to delete a status at all versus archiving, updating, or reordering statuses, and no alternative tool is named.

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

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

The description says the task is marked as deleted 'without permanent removal', but the annotations declare destructiveHint=true. This is a direct behavioral inconsistency: the annotation signals destructive behavior while the description frames the operation as non-permanent. No additional behavioral context about permissions, side effects, or restoration is provided.

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 immediately states the tool's use. It contains no repetitive or low-value content.

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

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

For a two-parameter mutation tool, the description gives only the soft-delete intent and omits any mention of permissions, side effects, or restoration. More importantly, that intent conflicts with destructiveHint=true, leaving the agent with an unreliable behavioral 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?

Schema description coverage is 100%, so the schema already explains board_id and task_number. The description adds no parameter syntax or constraints beyond what the schema provides, which is acceptable given the high coverage.

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

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

The description states a clear verb and resource: marking a task as deleted. It also clarifies the operation is non-permanent, which is useful scope detail. However, it does not explicitly differentiate this tool from sibling tools such as restore_task or other delete_* tools.

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

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

The phrase 'Use this to mark a task as deleted without permanent removal' gives a clear usage context. It does not mention when not to use the tool or point to restore_task or any permanent-deletion alternative, so there is no explicit 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?

Annotations already cover read-only, idempotent, closed-world safety, but the description adds real value beyond them: it discloses that access is membership-gated and, critically, that unknown-namespace, unknown-board, and non-member errors are indistinguishable — preventing an agent from attempting to diagnose or enumerate via retries. It does not say what is returned or how archived boards behave.

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 before the resolution mechanics and the error semantics. Every sentence carries distinct 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 2-param read tool with full schema coverage, rich annotations, and no output schema, the description covers purpose, resolution order, and failure modes. The only real gap is that the return payload (a board object? which fields?) is never characterized, which matters since no output schema exists.

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

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

Schema coverage is 100%, with the board_code constraint (3 chars, case-insensitive, legacy Unicode) already documented in the schema. The description adds the ordering relationship between the two parameters (namespace resolved first, board scoped within it), which is a modest but genuine semantic addition. 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?

"Canonical lookup for a board" names a specific verb (resolve/retrieve) and resource, and the second sentence spells out the exact resolution path (namespace slug → 3-char board code). This implicitly separates it from list_boards/search_tasks, though no sibling is named explicitly.

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

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

Usage is only implied: the tool requires both a namespace slug and a board code, so an agent can infer it is for known-identifier fetches rather than discovery. There is no explicit "use this instead of list_boards when..." guidance or statement of prerequisites (e.g., needing membership).

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral detail: the payload is the contents of the root AGENTS.md file and the result is null when no prompt is set — important since there is no output schema.

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

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

Three compact sentences with zero padding: the purpose and the pre-work instruction are front-loaded, followed by the return-value contract. Every clause carries information an agent needs.

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

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

For a single-parameter read with no output schema, the description covers both side of the contract (what content comes back, and the null case). It does not mention error or permission conditions (e.g., board not found / not a member), a minor remaining gap.

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

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

Only one parameter, and the schema documents board_id at 100% coverage ('Board ID to read the prompt for'), so the baseline is 3. The description adds no syntax, format, or validity details beyond that.

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 (fetch) and a precisely scoped resource (the board-level agent prompt / root AGENTS.md file), so the agent knows exactly what comes back. It does not explicitly name the sibling it differs from (e.g., list_board_files or update_board_file), which keeps it 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?

'Read this into your context before working a board' is an explicit when-to-use directive, which is more than most tool descriptions provide. There are no when-not conditions or named alternatives (e.g., use list_board_files to enumerate all files instead).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world. The description adds genuinely new behavioral context: reads are 'effective', returning the default when a value is unset (lazy), and it describes the return shape ({ key: value }). That is meaningful beyond the annotation set.

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 clauses in one sentence, front-loaded with the verb and resource, then behavior, then return shape. No padding 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 describing the returned { key: value } object(s), plus the effective/default semantics. The main gap is the absence of a pointer to get_board_settings_schema for discovering valid keys.

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

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

Schema coverage is 100%, and the schema already documents both parameters including the 'omit to read all' behavior and an example key. The description's 'stored value or default when unset' framing adds mild semantic value but no syntax or key-naming detail 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 ('read') and resource ('a board's effective settings') and explains the effective-value semantics (stored value or lazy default). It does not distinguish itself from adjacent siblings such as get_board_settings_schema or set_board_setting, so it falls 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?

The description gives per-parameter usage ('Pass a key to read one setting; omit it to read all'), which is helpful, but it never says when to prefer this over get_board_settings_schema (to discover keys) or set_board_setting. Usage context 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value by noting the metadata is board-independent, telling the agent no board context is required even though nearly every sibling is board-scoped.

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 compact sentences with the core action front-loaded and the prerequisite-for-write guidance last. 'Use this command to' is mild filler but nothing else is wasted.

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

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

For a single-optional-parameter read tool with full annotation coverage and no output schema, the description covers what it returns ('json-schema-like' types/defaults), how to scope the call, and when to call it. Nothing an agent needs 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 key parameter already documents 'Omit for all available settings'. The description's 'pass a key to inspect one setting; omit for all' largely restates the schema, adding only the downstream rationale of validating keys before a write.

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 board settings, their types and defaults in a json-schema-like form. It clearly differs from set_board_setting (write) but never distinguishes itself from the sibling get_board_settings, which is the most likely confusion point.

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 call conditions: pass a key to inspect one setting, omit for all, and call this before set_board_setting to learn valid keys and types. It lacks an exclusion against get_board_settings, so the 'when not to use' half is missing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful scope context ('calling user's tasks', 'across all accessible boards', computed on demand), but says nothing about cost, aggregation limits, or how large result sets are handled. Under annotation coverage the added value is modest.

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

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

Two sentences with no filler, front-loading the operation and scope, followed by intent examples. Every clause carries information the agent can use.

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-param read tool with rich annotations and no output schema, the enumerated digest sections stand in for a return-value description, which is nearly sufficient. A brief note on how 'stale' is defined or on result volume would close the remaining gap.

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

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

Zero parameters, so there is no schema semantics to explain; baseline 4 applies. The description correctly implies no filtering inputs by framing the result as the caller's own digest.

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 'compute ... digest' with an explicit resource scope: the calling user's tasks across all accessible boards. It also enumerates the digest sections (overdue, stale, new assignments, open count, recently completed), which makes the output concept concrete. It stops short of naming the closest sibling (my_work) so the agent must still infer the distinction.

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 usage context with two sample questions ('what needs my attention?', 'what's my work summary?'), which maps well onto realistic agent intents. No explicit when-not or named alternatives, so the agent is not told when to prefer my_work or list_tasks instead.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description then adds genuinely non-obvious context beyond the annotations: the returned id is opaque, app-scoped, and stable across token refresh, reconnection, and display-metadata changes — exactly what an agent needs to know before caching or comparing ids. It does not, however, say anything about auth failure behavior or scope requirements.

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

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

Two sentences, both front-loaded with the essential claim: first what is returned, then why the returned id is trustworthy. There is no filler and nothing is buried.

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 an output schema present and rich annotations, the description doesn't need to explain return fields, and the stability note covers the main operational gotcha. A brief statement of when to call it (e.g., to verify identity after a token refresh) would close the remaining gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is a 4. The description correctly implies the credential context is derived from the request itself rather than passed as an argument.

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 ('Return') and a specific resource ('the profile represented by this request's authenticated credentials'), which makes clear this is a self-scoped identity lookup rather than an arbitrary user lookup. It stops short of distinguishing this from siblings explicitly, but no sibling tool in the list covers the same operation, so ambiguity is low.

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 'this request's authenticated credentials' implies the use case (identify the caller of the current session), but the description never states when to reach for this tool, nor does it flag any exclusions or follow-up tools. Usage is inferable rather than instructed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered; the description adds useful context by itemizing exactly what the aggregate bundle contains (handoff, attention counts, top tasks, activity). It does not state how many 'top' tasks are returned, whether the handoff may be absent, or any cost/latency of the aggregation.

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: the first sentence defines the payload, the second handles when to call. Slightly long and list-heavy, but every clause (handoff, attention snapshot, top tasks, activity) carries real information rather than restating the 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?

There is no output schema, and the description compensates by enumerating the return payload contents, including the attention snapshot sub-counts (blocked / overdue / due soon / unassigned / stale). For a one-parameter read tool this is complete enough to call and interpret 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?

Single required board_id with 100% schema description coverage, so the schema already documents the parameter. The description only echoes scope with 'for a board' and adds no format or sourcing guidance (e.g., where to obtain the board_id). Baseline 3 applies.

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

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

States a specific verb+resource ('get the full project context for a board') and then enumerates the payload: latest session handoff, attention snapshot, top open tasks, recent activity. That enumeration distinguishes it from siblings like get_board_prompt, list_tasks, and get_digest without the agent needing to open 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 says to call it at the START of a session and gives concrete trigger utterances ('continue where we left off', 'what's the state of the project', 'resume our work'), plus the key condition of a NEW chat after a saved handoff. It names no alternative tool, but the trigger conditions are precise enough that routing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the payload fields an agent will receive, but says nothing beyond that — e.g., what happens if the task number doesn't exist in the board, or any permission requirements.

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

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

A single front-loaded sentence with no filler; the purpose and the returned fields are stated before anything else. Nothing could be trimmed without losing content.

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

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

With only two well-documented required parameters and rich annotations, the main gap left is return shape — and the description compensates by listing the fields returned despite there being no output schema. Only the missing-task/error behavior keeps it from being fully 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%: board_id and task_number are both documented in the schema with their scoping semantics ('board scope'). The description adds nothing about parameters, so the baseline 3 applies — the schema does all the work here.

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

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

States a specific verb (read) and a specific resource (one task), and enumerates the fields returned (description, deadline, tags, status, assignee). 'One task' implicitly separates it from the sibling list_tasks/search_tasks, though no sibling is named 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' signals the single-record retrieval case, so usage is implied rather than stated. There is no explicit guidance on when to prefer list_tasks or search_tasks instead, or what preconditions (e.g., needing board_id and task_number) must hold.

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

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

Annotations already declare that this is a mutation with non-destructive, non-idempotent semantics. The description adds useful behavioral context beyond that: the invitee receives a notification and must accept, and the caller must be owner/admin.

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 short and front-loaded: purpose first, then acceptance behavior, then permission requirement. Minor filler in 'Use this command to' keeps it from being maximally tight.

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

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

For a simple three-parameter invitation tool with a complete schema and annotations, the description supplies the key flow and permission context. It leaves some invitation edge cases and sibling differentiation implicit, but is broadly sufficient to invoke correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the input schema. The description adds no additional parameter meaning or formatting 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?

State a specific verb and resource: invite a user to a board. Clear enough to act on, but it does not distinguish itself from the close sibling add_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?

The description implies usage through 'Use this command to invite' and states an owner/admin prerequisite. It does not explicitly say when to choose this instead of add_board_member or otherwise route the agent among closely related invitation 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?

Adds two non-obvious behaviors beyond the annotations: the plaintext secret is returned exactly once and must be stored immediately, and the caller must be an org owner/admin. It leaves one ambiguity — whether 'rotation' invalidates the previous key or whether revoke_agent_key must be called separately.

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 the usage condition, then the two operational warnings. Every sentence carries information an agent needs; nothing is wasted.

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

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

For a non-idempotent mutation with no output schema, the description covers the missing piece an agent would otherwise guess at (the one-time plaintext return) plus the authorization requirement. Combined with a fully documented schema, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% and the schema already explains the name default, the scope enum (including that enforcement is planned), and both required slugs. The description adds no parameter-level detail of its own, 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 ('Mint') and resource ('new API key for an agent member'), with the scope of the organization. It is trivially distinguishable from the nearest sibling, revoke_agent_key, and from create_agent, 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?

'Use for rotation or additional keys' gives a concrete trigger condition, and 'Requires organization owner/admin' states a prerequisite. It stops short of naming an alternative (e.g., revoke_agent_key for retiring an old key) or explicitly excluding first-time issuance via create_agent, so it earns a 4 rather than a 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the description earns credit for adding what annotations cannot: the permission requirement and the fact that agent rows carry active API-key counts and last key use. It does not mention pagination or result limits, which is the remaining 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 sentences, zero filler: the operation and returned data come first, the authorization constraint second. Nothing 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 read-only single-parameter list tool with no output schema, the description covers what is listed, the special agent fields, and the access requirement. It stops short of describing result shape or pagination, but an agent has enough to call it correctly.

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

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

Schema coverage is 100% and there is a single required parameter, so the schema already documents it. The description adds only that the slug identifies an organization, which is marginal beyond 'Namespace slug of the organization' 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?

The description uses a specific verb ('List') plus resource ('members of the organization') and scopes it via the namespace slug, which is clearer than the bare title 'List agents'. However, it does not distinguish itself from the sibling 'list_namespace_members', which an agent may reasonably consider interchangeable.

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 states the authorization prerequisite ('Requires organization owner/admin'), which is genuine usage context. But it gives no guidance on when to choose this over 'list_namespace_members' or 'create_agent'/'delete_agent' workflows, leaving the main selection ambiguity unresolved.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behavior context about the empty-list case and the guaranteed AGENTS.md root entry. It stops short of saying anything about ordering or size limits, but for a simple list operation this is solid added value.

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

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

Two tight sentences with the core purpose front-loaded and the return-value caveat second. The parenthetical 'multi-file-ready prompt store' is slightly jargon-heavy but does real explanatory work.

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, non-destructive list operation with full annotation coverage and no output schema, the description covers purpose and the notable empty-state semantics. Ordering, pagination, and file metadata are unstated but the annotations plus the v1 caveat make the call safe and correct.

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 and schema description coverage is 100%, so the schema fully documents board_id. The description adds no syntax, format, or validity meaning beyond it, which is the expected baseline of 3.

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

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

States a specific verb and resource ('List the board's named files') and parenthetically identifies what those files are (the multi-file-ready prompt store). It implicitly distinguishes itself from get_board_prompt by talking about a set of files rather than one prompt, though it never names that 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?

There is no statement of when to call this versus get_board_prompt or update_board_file, and no prerequisites or exclusions. The only contextual sentence describes what the return value means, not when to reach for the tool.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds the role vocabulary of the response, which is useful, but says nothing about whether pending invitations are included, ordering, or pagination behavior on large boards.

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 zero filler; the purpose and the role vocabulary appear immediately. It is efficient, though the brevity is also the source of the missing scoping detail.

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

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

For a simple read-only list tool with full schema coverage and dense annotations, the description is adequate but thin: it leaves open whether pending invitees are returned and whether results are paginated or ordered, both of which affect how an agent interprets the output.

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 and schema description coverage is 100%, with the schema itself stating 'Board ID to list members for.' The description adds no syntax or format guidance 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+resource (see all board members) and even enumerates the role values returned (owner/admin/user), so an agent knows exactly what comes back. It does not explicitly distinguish itself from near-siblings like list_namespace_members or list_pending_invitations, but the resource scope (board) 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 command to see all board members' implies the read use case but gives no when-to-use/when-not conditions and names no alternative. Given siblings such as list_pending_invitations and invite_board_member, a sentence about whether invited-but-not-yet-joined users appear here would have resolved real ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. Beyond that the description adds nothing behavioral: no defaults for include_archived vs only_archived, no pagination/limit behavior, no note on what an empty result means.

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 zero filler. It is efficient, though so terse that the brevity comes at the cost of missing detail rather than being a model of denseness.

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, fully annotated, zero-required-parameter list tool with no output schema, the description is just barely sufficient to select the tool. It leaves the agent guessing about the archive-flag interaction and the shape of the result.

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 (code, title, limit, only_archived, include_archived) are already documented with match semantics. The description adds no extra meaning, so the baseline 3 applies.

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

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

The phrase 'discover boards' conveys the resource and a retrieval intent, but it is a vague verb that never states this is a filtered list operation or what it returns. It also does not distinguish it from siblings like get_board_by_namespace, which also surfaces a board.

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

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

It gives an explicit workflow trigger: run this before creating or filtering tasks. That is real context an agent can act on, though no when-not conditions or alternative tools (search_tasks, get_board_by_namespace) are named.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description focuses on what the annotations cannot express: deduplication of tags, first-seen casing preservation, and case-insensitive sorting. That is genuinely useful behavioral detail. It does not mention an empty-board result or whether archived tasks contribute tags, which keeps it from 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 load-bearing: the first gives purpose and workflow placement, the second gives return semantics. No filler and the usage cue is front-loaded.

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

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

For a simple one-parameter read tool with no output schema, the description supplies everything an agent needs: what it returns, how results are ordered and deduplicated, and how it fits before list_tasks. Nothing material is missing.

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

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

There is a single required board_id and schema coverage is 100%, with the schema itself stating 'Board ID to list tags from.' The description adds nothing about the parameter (e.g., behavior on unknown or inaccessible board IDs), 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 immediately distinguishes it from the neighboring list_tasks filter flow. An agent can tell exactly what it gets back: tag strings, not tasks.

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

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

Gives explicit forward guidance: call this before filtering with list_tasks, which is the primary legitimate use. It stops short of stating when not to use it (e.g., when tags are already known or when searching tasks directly), but the intended sequencing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds only that results are scoped to one task; it says nothing about ordering, pagination, or what happens when the task has no checklist, which is the kind of context that would raise this above baseline.

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 inputs. The second sentence is mildly redundant against the schema's required fields, but nothing is wasted.

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

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

For a simple read-only list tool with full schema coverage, strong annotations, and no output schema, the description is sufficient to call it correctly. Only minor gaps remain, such as item field contents and empty-result behavior.

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

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

Schema coverage is 100%, with both board_id and task_number fully documented in the schema, so the baseline is 3. The description restates the two required parameters ('Provide board_id + task_number') without adding format, constraint, or scoping detail 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?

The description names a specific verb and resource ('retrieve all checklist items') and bounds it to a single task, so an agent knows exactly what it returns. It does not distinguish itself from nearby siblings such as add_checklist_item or update_checklist_item by name, but the read-only retrieval intent 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' implies the use case, but there are no explicit when-not conditions or pointers to alternatives (e.g., get_task for broader task detail). Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that the result is the complete set of comments ('all'), without mentioning ordering, pagination, or whether deleted comments 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 short sentences, front-loaded with the purpose before the parameter callout. The second sentence is largely redundant with the schema's required array, 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?

For a simple filtered-list read tool with rich annotations and fully documented params, this is close to sufficient, but with no output schema the agent cannot learn the shape of a returned comment (author, timestamps, pagination), and the description does not fill that 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%: board_id ('Board ID where the task belongs') and task_number ('Task number in board scope') are already documented. The description merely repeats that both must be provided, adding no format, scoping, or validation 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 ('retrieve all comments') plus the scope ('for a specific task'), so an agent can instantly tell it apart from add_comment or delete_comment in the sibling list. It stops short of explicitly naming the write siblings it is not, which keeps it from 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?

'Use this to retrieve all comments' implies the usage context, and it names the two required inputs. There is no explicit statement of when to prefer it over list_task_activity or search_tasks, and no exclusions, so guidance remains implied rather than 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful context about roster composition and the workspace-owner authorization requirement. It does not mention pagination or return shape, so it falls short of the highest score.

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 one front-loaded sentence that states the listing purpose, roster categories, and owner prerequisite. Every phrase adds useful information, including the parentheticals about editable explicit members and org namespaces.

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 read-only tool with full schema coverage and rich annotations, the description supplies the important roster composition and authorization context. It does not describe pagination or exact return fields, but the roster categories give enough sense of the output 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?

There is only one parameter, namespace_slug, and schema description coverage is 100%, so the schema already documents it. The description's phrase 'of a namespace' adds no format or syntax details 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 ('List') and resource ('unified member roster of a namespace'), then breaks the roster into structural owner, explicitly added members, and organization-inherited members. This clearly distinguishes it from siblings such as list_board_members and list_namespaces.

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 clear prerequisite: 'Requires the workspace owner.' It implies use for namespace membership listings but does not explicitly name alternatives or when not to use it. That is enough context for a simple list tool, but lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the description's main added value is the visibility scope: personal namespace plus organization namespaces the user owns or is a member of. That is useful behavioral context beyond the annotations, though it does not cover ordering, empty results, or response 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?

The description is two sentences, front-loads the core action and scope, and includes a concrete usage note. Every sentence adds relevant information without 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 zero-parameter, read-only listing tool with rich annotations and no output schema, the description is complete enough: it explains what is listed, whose namespaces are included, and why an agent would call it. Nothing essential 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?

The tool takes zero parameters, so there is no parameter semantics to document. The baseline for a zero-parameter tool is 4, and the description does not need to compensate for missing parameter documentation.

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: 'List all namespaces'. It also clarifies the scope as the user's personal namespace plus organization namespaces they own or belong to, which distinguishes it from related tools like list_namespace_members.

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 sentence 'Use this to discover where boards can be created or moved' gives clear context for when to call the tool. However, it does not explicitly name alternatives such as list_namespace_members or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and a closed-world scope, so the safety profile is fully covered. The description adds one genuinely useful behavioral fact — that results are limited to clients the caller owns, not all clients — but says nothing about pagination, ordering, or behavior when the caller owns none.

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 resource and ownership scope front-loaded and the returned fields packed into a parenthetical. No filler, no restatement of the title beyond what the field list adds.

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

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

With no parameters and no output schema, the description does the needed work by naming the fields an agent will receive (client_id, name, redirect URIs, scopes, revocation status). The only real gap is the absence of pagination or result-size expectations 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?

The tool takes zero parameters and the schema is empty at 100% coverage, which establishes the baseline of 4. The parenthetical field list describes return content rather than parameters, so it neither helps nor hurts this dimension.

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 (List) plus resource (OAuth2 clients) with an explicit scope qualifier ('you own') and an enumeration of the returned fields. It implicitly separates itself from create_oauth_client and revoke_oauth_client by verb, but never names those siblings to make the distinction unambiguous.

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

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

Usage is only implied: an agent can infer this is the read path for inspecting OAuth2 clients before revoking or auditing them. There is no explicit when-to-use, no mention of when a different tool (e.g., a per-client getter) is preferable, and no prerequisites stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds one genuinely useful behavioral fact — the caller must be a board member to use the board_id mode — but says nothing about whose invitations are returned in each mode (sent vs received) or result ordering/limits.

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

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

Two short sentences, zero filler, and the no-argument case is front-loaded before the filtered case. Every clause carries information an agent needs.

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

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

For a single optional-parameter read tool with full annotation coverage and no output schema, the description is nearly sufficient. The only real gap is clarification of what an 'invitation' is here (incoming to the caller vs. sent by them), which affects interpretation of results.

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 explains that board_id is an optional filter with the same omitted-behavior semantics. The description restates this almost verbatim, adding only the membership constraint, 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 (list pending invitations) and splits behavior into two clearly-scoped modes based on board_id. It is distinguishable from write-side siblings like invite_board_member or respond_to_invitation, though it never names 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?

Explicitly says when to omit board_id (your own invitations) versus when to supply it (board-level invitations), and adds the membership prerequisite. It stops short of naming alternatives such as respond_to_invitation for acting on the results.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds essentially nothing beyond them — no mention of permissions, whether statuses are board-scoped or global, or that ordering is returned as a stable sequence.

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 padding, front-loaded with the resource. The only cost is the filler phrase 'Use this command to,' which delays the actual content.

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

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

For a simple read-only list tool with rich annotations and full schema coverage, little is strictly required. However, with no output schema, the description could usefully state that it returns each status's identifier, name, and position — 'ordering' hints at this but never makes it explicit.

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

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

With a single parameter at 100% schema coverage and a schema description that already explains the default-to-active-board behavior, the schema carries the full burden. The description adds no meaning about board_id or what happens when a non-active board is requested.

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) and resource (board status catalog and ordering), which is clear enough for an agent to know it returns the list of statuses for a board. It does not name or distinguish itself from siblings such as create_status, update_status, or reorder_statuses, so the read-vs-write boundary is only inferable from the verb.

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 'Use this command to...' phrasing is a generic lead-in with no condition for when this tool is preferred over alternatives like reorder_statuses or get_board_settings. No prerequisites, exclusions, or follow-up 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds the return shape (a timeline of activity entries) and the action types included, but omits ordering (oldest/newest first) and pagination behavior, which matter for a paged timeline.

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, zero waste, with the scope-defining content front-loaded. Nothing needs to be trimmed.

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 simple read tool with rich annotations, a fully described schema, and no output schema, so the description need only convey purpose and return shape - both present. The only real gap is timeline ordering, which an agent may care about when paging.

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?

All four parameters are fully documented in the schema including defaults for limit (20) and offset (0), so coverage is 100% and the baseline applies. The description adds no additional meaning about board_id/task_number scoping or how limit interacts with the timeline.

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 (read) and resource (history of actions on a task) and enumerates the action types included (create, update, status changes, comments), which separates it from create/update_task. However, it never explicitly distinguishes itself from close siblings like list_comments or get_task, which surface overlapping data.

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 usage context but names no alternatives and gives no exclusions - an agent must infer that comment bodies come from list_comments and current state from get_task. Implied usage only.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior, so the description earns credit for adding the authorization model (board membership or public board) and the shape of what is returned. It does not state pagination, ordering, or behavior for an unknown task, which keeps it below a 5.

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

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

Two short sentences, zero waste: the operation and returned fields come first, and the auth constraint follows. Nothing is repeated from the title or schema beyond necessary framing.

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 two-parameter read tool with no output schema, the description covers purpose, access, and the returned field set, which is enough to invoke it correctly. Missing pagination or empty-result behavior keeps it short of 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%: board_id and task_number are both documented in the schema, and the description adds only the framing 'of a board task' without new syntax or constraints. Baseline 3 applies when the schema carries the parameter burden.

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 plus resource: 'List the attachments of a board task', followed by the exact fields returned (id, name, size, mime type, caption). The scoping to a task (via board_id + task_number) implicitly distinguishes it from the sibling list_board_files, but no sibling is named 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 gives an access prerequisite ('Read access requires board membership (or a public board)') but no when-to-use guidance, no exclusions, and no pointer to the board-level alternative list_board_files. Usage is only inferable from the resource named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the ability to filter by deletion state, but it does not explain default deletion behavior, pagination, ordering, or what the result looks like beyond what the schema already says.

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 immediately says how to use the tool and then lists the relevant filter dimensions. It contains no filler and is appropriately sized for an overview.

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

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

For an 11-parameter read-only list tool with complete schema coverage and clear annotations, the description is broadly complete: it identifies the tool's purpose and the filter set. Minor gaps around default deletion handling and pagination behavior are mitigated by the detailed schema.

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

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

Schema description coverage is 100%, so the parameter schema already documents all 11 parameters precisely, including aliases, date formats, and filter behavior. The description only lists filter categories at a high level and adds no syntax or semantics beyond the schema.

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

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

The description states a specific verb (inspect) and resource (task backlog) and enumerates the filter dimensions, so the tool's basic function is clear. It does not explicitly differentiate this tool from the close sibling search_tasks or explain whether it is board-scoped versus cross-board.

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 usage context with 'Use this to inspect task backlog by...' followed by the available filters. It does not state when to prefer search_tasks, get_task, or my_work instead, but it provides enough context to know the intended use.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety framing is partly covered; the description still adds real value by disclosing the URL change side effect and the uniqueness precondition. It omits mutation-specific context the annotations don't cover, such as required permissions on both namespaces, whether the move is reversible, and whether old links redirect or break.

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, each carrying distinct information: action and scope, uniqueness precondition, side effect, and intended use case. No filler and the action is front-loaded.

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

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

For a two-parameter mutation with no output schema, the description covers purpose, precondition, and post-move side effect adequately. Gaps remain around authorization requirements and whether the move can be undone, which matter for a namespace-transfer operation.

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

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

Schema description coverage is 100%, and the schema itself documents both board_id and namespace_slug including the list_namespaces discovery hint, so the baseline is 3. The description's remark about the 3-character code being unique in the target namespace adds useful constraint context for namespace_slug but no format or semantics 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 plus the source/target scope ('from its current namespace to a target namespace'), which is far more precise than 'Move board' alone. It does not explicitly differentiate itself from close siblings like transfer_board_ownership, bind_board_to_group, or update_board, so an agent must infer the distinction.

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 concrete use case ('consolidate boards into an organization namespace') and an important precondition (code must be unique in the target namespace), which tells the agent when the call is appropriate. It stops short of naming alternatives or exclusions, e.g. when to use transfer_board_ownership instead.

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

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

Annotations only tell the agent this is a non-idempotent, non-destructive write. The description adds genuinely valuable consequences the agent could not infer: the task receives a new number in the target board, and status resets to the target default when the current status is absent there. It stops short of saying whether comments, checklists, or history follow the task.

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 primary action is front-loaded and the two behavioral caveats follow immediately. Nothing could be cut without losing 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 mutation tool with no output schema, the description covers the core outcome but leaves open important questions: what happens to comments, checklist items, attachments, and activity history, and whether the source task disappears. Adequate but with clear gaps for an agent handling a task move.

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 three parameters are already documented in the schema and the baseline of 3 applies. The description adds no further parameter-level detail such as whether task_number must refer to an open task or how board IDs are obtained.

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 a task between boards') that is clearly distinct from siblings like update_task, clone_board, and move_board. It doesn't explicitly name those alternatives, so it falls short of the 5 bar, but the purpose is unambiguous.

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

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

The opening 'Use this to transfer a task between boards' implies the usage context, but there is no guidance on when to choose this over alternatives (e.g., clone_board plus delete_task) or any preconditions. 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds meaningful context beyond that: a hard ceiling of 100 results, recency-based ordering, and cross-board scope. It does not say whether results are silently truncated at 100 or how to page past that limit, which is the one 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?

Three tight sentences: behavior first, then use cases, then the optional scoping parameter. Nothing is padded and the most decision-relevant facts are front-loaded.

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

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

For a one-optional-parameter read tool with full annotation coverage and no output schema, the description covers scope, cap, ordering and usage. The only missing piece an agent would want is what happens at the 100-result boundary (truncation vs. pagination).

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 fully documented in the schema, so the baseline is 3. The description reinforces the intent ('scope to a single namespace') but adds no syntax or default-behavior detail, and it refers to the parameter as 'namespaceSlug' while the schema names it 'namespace_slug' — a minor naming inconsistency.

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 ('Returns ... tasks') plus the exact scope: assigned to or created by the caller, across all accessible boards. The result cap (100) and ordering (most recent update) further pin down what the tool does, distinguishing it from board-scoped siblings like list_tasks or search_tasks.

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

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

Gives concrete use cases ('what's on my plate?', surfacing overdue/stale work) and explains when to pass the namespace slug. It stops short of naming alternatives such as list_tasks or search_tasks and saying when those are preferable.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds non-obvious semantics the annotations can't convey: on group-linked boards the member reverts to a regular Telegram member rather than being fully removed, and role-based authorization limits.

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

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

Front-loaded with the core action, then layers in the group-link caveat and permission rules. Four tight sentences, all loading-bearing; slightly dense but 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?

Covers the behavior, constraints, and permission model needed to invoke correctly, with output schema absent but return value relatively self-evident for a removal operation. Rich enough for an agent to act without trial and error.

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 are documented in the schema, so the baseline is 3. The description adds meaning by implying board_id determines the board type behavior, but doesn't elaborate on user_id format 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 ("remove a member from a board"), clearly distinct from siblings like add_board_member, invite_board_member, and remove_namespace_member. It doesn't explicitly name an alternative, but the purpose is unambiguous.

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

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

Provides concrete when/when-not guidance: Telegram-only members cannot be removed, and a permission hierarchy is spelled out (owner removes admin/user, admin removes user, owner cannot be removed). It stops short of explicitly routing to sibling tools for adjacent cases.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description's job is to add the operational details it does: an authorization prerequisite (requires the workspace owner) and the immunity rules that determine which rows this can and cannot touch. It omits what happens to the removed user's tasks/comments and whether removal is reversible or re-invitable, which are the remaining behavioral gaps for 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?

Four tight sentences with no filler: the action comes first, then the immunity/exception rules, then the auth requirement. Every clause carries information an agent could otherwise get wrong.

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 with full schema coverage and no output schema, the description covers the action, prerequisites, and exclusion cases well. Only the post-removal effects (access revocation, orphaned assignments) are unaddressed.

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

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

Schema description coverage is 100%, with both user_id and username documenting the 'either/or is required' rule and pointing to list_namespace_members for lookup. The description adds nothing about parameter semantics 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 (remove an explicitly-granted workspace membership / NamespaceMember row) and immediately scopes it away from two adjacent concepts: the workspace owner and org-inherited memberships. This is enough to separate it from remove_board_member and add_namespace_member without opening 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?

Gives clear exclusion conditions — the owner cannot be removed, inherited org memberships must be managed on the org surface, and per-board memberships survive. It stops short of naming the sibling to use instead (remove_board_member, list_namespace_members for discovery), so the alternative routing is implied 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?

Annotations cover the safety profile (not read-only, non-destructive), so the description could have spent its space on the real unknown: whether ordered_status_ids must be a complete list and what happens to statuses omitted from it. That key behavioral ambiguity is left unaddressed.

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 short sentence that front-loads the required parameter. Nothing is wasted, though there is very little content to structure.

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 full schema coverage and annotations, the basics are covered and no output schema is needed. However, the all-or-nothing semantics of the ordering payload are missing, which is the one thing an agent must know to call this correctly.

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

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

Schema coverage is 100%, so both board_id (with its default to the active board) and ordered_status_ids are documented in the schema itself. The description repeats the parameter name but adds no constraint such as completeness or duplicate handling, 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?

The description names a specific verb ('set deterministic status ordering') and resource ('status ordering for a board'), which clearly separates it from single-status siblings like update_status or list_statuses. It stops short of explicitly naming those siblings, but the action 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?

It only says to supply orderedStatusIds; there is no guidance on when to use this versus update_status or create_status, no prerequisites, and no note about whether the board must already have statuses. Usage is inferable from the name only, not from the text.

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

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

The annotations already declare that the tool is non-read-only, non-idempotent, non-destructive, and closed-world. The description adds the pending-invitation state and token source, but it does not explain what accepting or rejecting does to board membership, whether the token is consumed, or what happens with an expired token.

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 well-structured sentence with the action and prerequisite front-loaded. Every clause carries useful selection or invocation information.

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

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

For a simple two-parameter mutation with annotations and no output schema, the description covers the essential selection and token-source information. It is slightly incomplete on the downstream effects of accepting or rejecting, but the core invocation context is present.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description restates that the token comes from list_pending_invitations and that the action is accept/reject, but it adds no format or semantic details beyond the schema.

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

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

The description states a specific verb and resource: accept or reject a pending board invitation. It also scopes the action to a token obtained from list_pending_invitations, which distinguishes it clearly from sibling tools such as list_pending_invitations and cancel_board_invitation.

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

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

It explicitly says when to use the tool: handling a pending board invitation, with the token coming from list_pending_invitations. It does not discuss exclusions or alternatives, but the operational context is clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds one useful behavioral fact 'previously archived' establishing a state precondition, but says nothing about failure modes (board not archived, already active), permission requirements, or whether tasks/members are restored with the board. Given annotation coverage, a 3 is appropriate.

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

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

One short sentence with zero filler, and the action plus the precondition are front-loaded. It is efficient but slightly under-specified rather than padded; nothing in it is wasted.

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

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

For a one-parameter mutation with annotations and no output schema, the essentials are present but the edges are unresolved: what happens if the board is not archived, what permissions are needed, and what state the restored board returns in. These are reasonable gaps for a simple tool but leave an agent guessing at the failure path.

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

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

There is a single parameter with 100% schema description coverage ('Board ID to restore.'), so the schema fully documents it. The description adds no additional meaning such as where to obtain the board_id or whether archived boards appear in list_boards. Baseline 3 applies when the schema does the work.

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

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

The description names a specific action ('recover') and a specific resource ('a previously archived board'), which clearly ties it to the sibling archive_board as its inverse. It stops short of explicitly naming siblings like restore_task, so the agent must infer the board-vs-task distinction from the resource noun 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?

'Use this to recover a previously archived board' implies the triggering condition (the board is currently archived), which is meaningful guidance. However, there is no explicit when-not, no mention of what to do if the board is not archived, and no note on required permissions or ownership.

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

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

Annotations already declare a non-read, non-destructive, non-idempotent mutation, so the bar is lowered. The description adds that the target task must be deleted, which is useful, but says nothing about permissions required, what happens if the task was never deleted or was purged, or whether the restore 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?

A single sentence with no filler; every clause contributes. The action verb is slightly back-loaded after the 'Use this with' clause, but nothing is wasted.

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

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

For a two-parameter, no-output-schema mutation whose annotations cover the safety profile, the definition supplies the key prerequisite workflow. Remaining gaps around failure modes and permissions are minor at this complexity level.

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 carry descriptions clarifying board scoping and that the task number refers to a deleted task. The description adds no syntax or formatting detail beyond that, so the schema baseline of 3 is appropriate.

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

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

The description names the specific action (recover deleted tasks) and the tool name/title reinforce restore_task. It distinguishes itself from restore_board by implication of 'tasks,' and from delete_task by direction, 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?

It states a concrete precondition workflow: pair with list_tasks using onlyDeleted/includeDeleted to find the deleted task first. There is no explicit when-not guidance (e.g., what to do for non-deleted tasks or whether archive exists as an alternative), 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds authorization requirements and the ownership constraint that annotations cannot express. It does not say what happens to the agent immediately after revocation, which is the remaining behavioral 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?

Three short sentences with no padding, and the destructive action plus its scope are front-loaded before the authorization detail.

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 destructive tool with full annotation coverage, this covers purpose, scope, and permissions adequately. The main omission is the post-revocation effect on the agent's access.

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 key_id parameter is fully documented in the schema, including its source (list output or web UI). The description's 'by id' adds nothing 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 and resource ('Revoke an agent's API key by id') and explicitly scopes it to agent-owned keys, adding that humans revoke their own. This cleanly separates it from revoke_oauth_client and from any human key revocation path.

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 applicability condition (only agent-owned keys) and a prerequisite (org owner/admin of an org the agent belongs to). It stops short of naming a concrete alternative tool for the non-agent case, but the exclusion is stated plainly enough to route an agent correctly.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds important nuance: existing tokens are not deleted, and no new authorizations will be allowed. That clarifies the scope of the destructive action beyond the annotation alone.

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

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

The description is two tight sentences with no wasted language. The primary action is front-loaded, followed immediately by the key behavioral consequence.

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 destructive tool with full schema coverage and annotations, the description covers purpose and the most important side effect. It could be slightly more complete by pointing to list_oauth_clients as the way to obtain client_id, but no critical information 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 schema already documents client_id as the numeric ID of the OAuth2 client. The description mentions the numeric ID but adds no additional syntax, format, 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 states a specific verb and resource: revoke an OAuth2 client by numeric ID. It is clearly distinct from siblings such as create_oauth_client, list_oauth_clients, and revoke_agent_key.

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 what the tool does but gives no explicit guidance on when to use it versus alternatives, such as list_oauth_clients to find the client_id or create_oauth_client for the opposite action.

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

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

Annotations already cover the safety profile (non-read-only, non-destructive, non-idempotent), and the description adds real context: the handoff is a durable board note intended for a future session, and `summary` must be an authored recap rather than a transcript. It stops short of saying what object is created or whether repeated calls create duplicate handoffs, which matters given idempotentHint=false.

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

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

Front-loaded with the definition and the timing instruction, then trigger phrases, then the summary constraint. Every sentence has a job, though the `summary` warning partially duplicates the schema text and could be trimmed.

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 output schema, the description covers purpose, timing, trigger phrases, and content expectations well. It leaves the return value (e.g., a handoff ID) and duplicate-call behavior unstated, minor gaps but real ones for a save 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 coverage is 100% and the schema descriptions already define `summary` as an authored done/next/blocked recap that is not a transcript, plus `links` examples and limits. The description largely restates the `summary` constraint with added emphasis ('YOUR OWN', 'list of raw messages') rather than adding new parameter semantics, 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 (save a session handoff) and defines the artifact concretely: a durable note capturing done / next / blocked / key links. It is clearly distinct from every sibling, which are task/board/comment CRUD operations, and even defines the required content of the record.

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 call it ('at the END of a working session so the next session can pick up') and supplies concrete trigger phrases the user might say. No sibling tool offers an alternative for this need, so the absence of a 'use X instead' line is not a gap.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds real behavioral detail beyond that: the hard cap of 50 results and ordering by last updated. It does not say what happens when the result set exceeds 50, which is the one remaining behavioral 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?

Three sentences, front-loaded with the purpose, then usage, then return behavior — no filler. The opening enumeration is slightly long but each clause maps to a real filter dimension.

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

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

With no output schema, the description usefully covers return shape (count cap, ordering), and all six optional parameters are documented in the schema. The missing pieces are pagination/truncation behavior and its relationship to sibling listing tools, which keeps it from a 5.

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

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

Schema description coverage is 100%, so every parameter (including enum-free priority/attention values) is already documented in the schema. The description only recaps the filter names and notes they are optional; it omits board_id scoping and adds no syntax detail, 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 ('find') and resource ('tasks') plus the exact filter dimensions and scope ('across all your accessible boards'). It is clear on its own, but never distinguishes itself from the similar siblings list_tasks and my_work, leaving the agent to guess which retrieval tool to pick.

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?

'All filters are optional — combine them to narrow results' gives concrete guidance on how to drive the tool and clarifies that an empty call is valid. It stops short of naming when to prefer list_tasks or my_work instead, so no exclusion criteria are offered.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent behavior. The description adds genuine context the annotations don't carry: that values are coerced server-side and which boolean spellings are accepted. It does not say what happens with an unknown key or an invalid value, which for a mutation tool is the remaining behavioral gap, so a 3 rather than 4.

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 plus one example, all front-loaded: purpose, coercion semantics, discovery prerequisite, then a concrete illustration. Nothing is redundant and the example 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-required-parameter mutation with full schema coverage and no output schema, the essentials are covered: how to find keys, what values are accepted, and the type coercion rule. Only edge-case failure behavior (unknown key, invalid value) is unstated.

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

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

Schema coverage is 100%, so baseline is 3; each property already documents itself, including the boolean coercion note. The description mostly restates the schema's coercion wording, and only the pointer to get_board_settings_schema for valid keys adds new 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 and resource: 'change a board setting', with the key/value shape implicit. It names the companion discovery tool get_board_settings_schema, which helps separate it from the read-side siblings, though it never explicitly contrasts with get_board_settings or update_board.

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

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

Gives clear operational context: use it to change a setting, and call get_board_settings_schema first to discover keys and types. The worked example (autoAddAssignees to "off") makes the intended use concrete. No explicit exclusions or when-not guidance, hence not a 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?

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds real value beyond them: the side effect that the current owner is demoted (default 'admin'), the authorization requirement (caller must be the owner), and an explicit irreversibility warning. It stops short of describing failure modes (e.g., invalid target ID, insufficient permissions) or whether the new owner can transfer back.