Dutify

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

Annotations already establish that this is read-only, idempotent, non-destructive, and closed-world. The description adds two useful behavioral facts: no selected workspace is required and no quota is reserved. It still does not explain return behavior or error conditions.

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-loads its main claims without excessive text. It is appropriately sized, though the phrase "fresh credential/workspace discovery" remains vague rather than fully informative.

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 should clarify what the tool actually returns, such as workspace details or credential/account information, and how it relates to sibling discovery tools. It does not provide that, leaving an important gap for an agent trying to invoke it correctly.

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

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

Schema description coverage is 100%, so both the account and workspace parameters are already well documented in the schema. The description does not add parameter-specific meaning beyond that, so the baseline of 3 applies.

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

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

The description says this is for "fresh credential/workspace discovery," which gives a general purpose but does not specify exactly what is returned or how it differs from siblings such as list_workspaces, list_accounts, or whoami. It is more than a pure tautology, but the purpose remains vague.

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 statement that it "does not require a selected workspace or reserve quota" implies it can be called before workspace selection, which is useful usage context. However, it gives no explicit when-to-use guidance versus alternatives and no 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 establish this is a non-destructive, non-idempotent write with open-world access. The description adds real value on top: it clarifies that comments can be internal-only via isInternal and names the required auth scope (`feedback:comments:write`), which the annotations cannot convey.

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

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

Three short fragments: action, optional-flag semantics, and auth scope. Front-loaded and every sentence has a distinct purpose with no filler.

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

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

For a mutation tool with annotations and no output schema, the description covers the action, the key optional parameter, and the permission requirement. It omits what the call returns (e.g., comment ID) and failure modes, which is a minor gap.

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

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

Schema coverage is only 40%, and the two undocumented properties (content, shortId) are obvious from name, while the description explains the non-obvious isInternal flag. That covers the semantic gap reasonably but adds nothing about shortId format or content length limits, so a baseline 3 is fair.

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

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

States a specific verb and resource ('Add a comment to a bug report'), which cleanly separates it from the request-oriented sibling fr_comment_request. It does not explicitly name that sibling or spell out the bug-vs-request distinction, keeping it just 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?

The isInternal flag's internal-only use case is explained, and the required API-key scope is given. However, there is no guidance on when to prefer this over fr_comment_request or fr_get_bug-style read paths, so usage is only implied.

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

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

Annotations already declare this as a non-read-only, non-idempotent, open-world write, so the safety profile is covered. The description adds real value beyond them: the internal-visibility semantics tied to the `View Internal Data` permission and the required `feedback:comments:write` API-key scope. It stops short of describing what happens on failure or duplicate submission.

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 key flag behavior, then the auth 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?

For a 5-parameter mutation with well-documented schema properties and full annotation coverage, the description supplies the missing permission and scope context. It doesn't indicate what a successful call returns (no output schema exists), which is 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?

Schema coverage is 80%, so the baseline would be 3, but the description meaningfully expands the sparse `isInternal` schema entry ("Default: false") by explaining what true actually does and what permission the visibility depends on. `content` and `shortId` remain self-evident from 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 (Add) and resource (a comment to a feature request), which unambiguously separates it from the sibling fr_comment_bug. An agent can distinguish the target resource without opening either schema.

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

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

Usage is implied by "Add a comment to a feature request", but the description never names fr_comment_bug as the alternative for bug comments, nor states prerequisites or when-not to use it. Guidance for isInternal is provided, but that is parameter-level, not tool selection.

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

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

Annotations already declare the mutation profile (not read-only, non-idempotent, open-world, non-destructive), so the bar is lower. The description adds real behavioral context: severity/productArea are resolved leniently by name, environment is an unconstrained free-form map, and the required auth scope. It stops short of stating what happens when a name fails to resolve or what is returned.

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, purpose front-loaded, with each subsequent sentence adding a distinct piece of non-redundant information (name resolution, environment shape, auth scope). 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 an 11-parameter mutation with nested object and no output schema, the description covers creation semantics and auth but omits what a successful call returns and how to obtain a valid boardSlug. Adequate to call it, incomplete for calling it correctly on the first try.

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 only 55%, but the description supplies meaning the schema lacks for the two resolution-sensitive params (severity, productArea are matched by name leniently) and clarifies the environment map's shape. The remaining undocumented fields (actualResult, expectedResult, stepsToReproduce) are self-descriptive by name, so the gap is modest.

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 bug report on a board,' which implicitly separates it from fr_create_request. It does not explicitly name or exclude the sibling request-creation tool, so an agent must infer the bug-vs-request 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?

The required API-key scope `feedback:bugs:write` is a genuine usage precondition, but there is no explicit statement of when to use this versus fr_create_request, nor guidance on discovering boardSlug via list_boards. Usage is implied rather than directed.

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 a non-idempotent, open-world, non-destructive write. The description adds real value beyond them: no turnstile token is required, API-key auth suffices, the required OAuth scope is `feedback:requests:write`, and the response includes the assigned shortId. It does not mention possible side effects (notifications, duplicate submissions on retry given idempotentHint=false), which keeps it out of 5 territory.

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

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

Four short sentences, zero filler: action first, then the non-obvious category behavior, then auth/return details, then the scope. Every sentence 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 6-param creation tool with no output schema, the description supplies the authentication model, permission scope, the return payload, and the one subtle parameter behavior. It falls short only on idempotency/retry guidance and on routing versus the sibling create tool.

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

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

Schema coverage is 67% and the description meaningfully augments it by explaining that `category` is resolved by name using a lenient match, which is more than the schema's "Optional category name". The remaining params (account, workspace, boardSlug, description) are handled by their schema descriptions.

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

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

The description gives a specific verb+resource ("Create a new feature request on a board") and the resource name implicitly distinguishes it from fr_create_bug and pm_create_task. It never names an alternative explicitly, but an agent can tell which create tool to pick by resource type alone.

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

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

Usage context is implied: this is the tool for feature requests, with no turnstile token needed and API-key auth sufficient. There is no explicit when-to-use/when-not statement relative to fr_create_bug, fr_vote_request, or a general pm_create_task, so the agent must infer the routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, yet the description still adds real value by stating the operation is permanent/irreversible, names the required `Manage Queue` permission, and gives the API-key scope `feedback:bugs:write`. It stops short of saying what happens to attached comments or whether a 404 occurs for a missing shortId, so it is strong but not exhaustive.

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 terse fragments, front-loaded with the action and object, then the permission gate, then irreversibility, then the scope. No filler and nothing an agent must scan past.

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

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

For a destructive mutation with no output schema, the description covers the safety profile (irreversible), authorization (Manage Queue, feedback:bugs:write) and target (a bug report), which is most of what an agent needs. Remaining gap is the undocumented required shortId, which is arguably a schema defect rather than a description one.

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

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

The description says nothing about any parameter. The two optional parameters (account, workspace) are well documented in the schema, but the single required parameter 'shortId' has no description anywhere, and the description does not compensate by explaining its format or where to obtain it.

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 ('Permanently delete a bug report') and the 'bug' qualifier plus the tool name distinguish it from fr_delete_request and other delete siblings in the same family. An agent can tell exactly what object this operates on without inspecting the schema.

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

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

The permission requirement and irreversibility imply this is a last-resort operation, but the description never states when to choose it over alternatives (e.g., fr_moderate_bug, fr_set_bug_visibility) or any precondition such as resolving vs. deleting. Usage is implied rather than directed.

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, but the description adds real value on top: the required `Manage Queue` permission, the `feedback:requests:write` API-key scope, and the exact 204 response. The irreversibility warning plus the confirm-first rule gives the agent the operational and authorization picture the annotations cannot express.

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?

Five short sentences, each carrying distinct information (action, permission, return code, safety rule, auth scope) with the destructive nature front-loaded. No repetition and nothing that could be cut without losing a fact the 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 destructive mutation with no output schema, the description covers what an agent needs to call it safely: authorization requirements, the 204 success signal, and irreversibility. The only remaining hole is the meaning/format of `shortId`, which is left entirely unspecified.

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 67% schema coverage and the two optional parameters (account, workspace) fully documented in the schema, the baseline is 3. Crucially, the sole required parameter `shortId` has no description in the schema and gets no explanation here either — the description never clarifies that this is the short identifier rather than a numeric ID, leaving the most important input ambiguous.

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?

"Permanently delete a feature request" is a specific verb + resource + permanence qualifier. It is unambiguously distinguishable from the sibling fr_delete_bug because the resource noun itself (request vs. bug) carries the differentiation, so an agent can select 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 a clear conditional rule of engagement: confirm with the user before calling unless intent is unambiguous. That tells the agent *how* to use it, but it never names an alternative path (e.g. moderating/hiding instead of deleting) or states when deletion is inappropriate versus a softer sibling like fr_moderate_request.

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 read-only/idempotent safety profile, and the description adds real context beyond them: internal notes and linkedIssueUrl are conditionally populated based on `View Internal Data` permission, and the required API-key scope is named. It stops short of describing not-found/error behavior or how comments are surfaced.

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

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

Three sentences, front-loaded with the identifying action, then the returned payload, then the permission/scope caveats. The field enumeration is dense but earns its place by telling the agent what data it can rely on.

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

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

With no output schema, the description usefully enumerates the returned fields, and the permission/scope constraints are documented. It is nearly complete for a simple read tool, missing only failure behavior and whether comments themselves are returned or just a count.

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 account, shortId and workspace. The description repeats the shortId example format but adds nothing for the multi-account `account` or `workspace` override parameters, 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 ("Get a bug report") plus the exact selector ("by short ID, e.g. BG-99"). This is clearly distinguishable from the list/create/comment siblings 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?

Usage is only implied by the singular-by-ID framing; there is no explicit statement of when to use this versus fr_list_bugs or fr_get_request, and no prerequisites called out. An agent can infer the case, but nothing routes it explicitly.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real context: the returned fields, that internal notes and linkedTaskIds are gated behind the `View Internal Data` permission, and the required `feedback:requests:read` API-key scope. That permission-conditional field population is exactly the kind of behavior an agent cannot infer from structured fields.

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 identifier requirement and followed by return contents and permission caveats; there is no filler and each sentence contributes new 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?

With no output schema, naming the returned fields is valuable and the permission/scope notes cover the main surprises. A minor gap remains around error behavior for unknown or inaccessible short IDs, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so all three parameters (account, shortId, workspace) are already documented. The description's only parameter-related addition is the "FR-42" example, which the schema already carries, so it 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?

States a specific verb and resource ("Get a feature request") plus the identifier type (short ID such as "FR-42"), which cleanly separates it from fr_list_requests and from the bug counterpart fr_get_bug.

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 infers this is the single-record lookup tool when it already has a short ID. There is no explicit statement about when to prefer this over fr_list_requests or when the ID is unknown, and no guidance on what happens when the request does not exist.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context: the required `feedback:bugs:read` scope and the fact that filters use lenient matching. It omits pagination, default result limits, and ordering behavior, which are the main remaining unknowns.

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 resource and board-slug scoping front-loaded, followed by filter behavior and the auth scope. No filler or redundancy.

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

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

For a 5-parameter list tool with no output schema, the definition covers purpose, filters, and permission scope but says nothing about result shape, paging, or default volume. An agent can call it, but cannot predict what comes back.

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 80%, so status, severity, account, and workspace are already documented in the schema. The description adds only that severity and status can be combined ('and/or'); boardSlug remains undocumented in both places. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List bug reports on a feedback board') and scopes it by board slug, which implicitly separates it from fr_list_requests. It does not name a sibling explicitly, so the differentiation is inferred rather than stated.

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

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

The description conveys the obvious context (list bugs for a given board, optionally filtered) and adds the required API-key scope. It never says when to use fr_list_requests vs fr_list_bugs, nor any exclusion or prerequisite beyond the permission string.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real behavior: lenient trimmed/case-insensitive matching, pagination via page/size, `q` overriding other filters, and the required API-key scope. It doesn't describe the response item shape, 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?

Four short clauses, front-loaded with the core action, then filters, search mode, pagination, and auth scope. No filler; each 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 read-only paginated list with no output schema, the description covers filtering, search semantics, pagination, and auth scope. The only gap is return-shape/envelope detail, which is minor since readOnly list tools are predictable and account/workspace params are documented in the schema.

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

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

With 78% schema coverage, baseline is 3, but the description adds meaning the schema lacks: the lenient normalized matching semantics for status/category/milestone (category and milestone have no schema descriptions at all) and the precedence rule for `q`. That meaningfully compensates for the coverage gap.

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

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

States a specific verb and resource ('List feature requests') plus scope ('on a feedback board (by board slug)'), which clearly separates it from fr_list_bugs and the fr_get_* siblings. An agent can identify it without opening the schema.

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

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

Gives explicit guidance on the two modes: filter by status/category/milestone, or pass `q` to search titles instead. It stops short of naming sibling alternatives (e.g. fr_get_request for a single item), so it's clear context without full 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 flag destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation risk is disclosed structurally. The description earns credit for adding context the annotations cannot carry: the required `Manage Queue` permission, the `feedback:moderation:write` API-key scope, and the case-insensitivity of the action value. It stops short of saying what approve/reject actually changes downstream, such as visibility or notifications.

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

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

Three short, front-loaded sentences with zero filler: action, then auth requirement, then scope. 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 destructive mutation with no output schema, the definition covers the critical operational facts: permission, scope, action semantics and the action enum. The remaining gap is the undocumented `shortId` requirement and any note on the effect of each action, which keeps it short of 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 coverage is 50%: `account` and `workspace` are well documented in the schema, while `shortId` has no description anywhere. The description compensates only for `action` with the case-insensitivity note; it says nothing about what a shortId is or how to obtain one, which is the one required parameter left unexplained.

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 (approve, reject, mark as spam) against a specific resource (a bug), and the enum in the schema confirms the three actions. It does not distinguish itself from the obvious sibling fr_moderate_request, so an agent must infer which resource type to target.

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 reader must know a bug needs moderation to select this tool. There is no explicit statement of when to use it versus fr_moderate_request, and no guidance on preconditions such as the bug being in a pending-moderation state.

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

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

Annotations already declare destructive=true, non-idempotent, non-read-only, so the description is not the sole source of behavioral disclosure. It still adds real value by stating the required permission and the write scope `feedback:moderation:write`, which are not in the annotations. It stops short of saying what happens to a request under each action (e.g., whether spam hides it or reject deletes it).

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

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

Three short sentences, front-loaded with the operations, then qualification, then auth constraints. Nothing superfluous.

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

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

No output schema exists, so return values need not be described, and the auth/permission/scope requirements plus the destructive annotation cover the safety picture for a mutation tool. The remaining gap is the per-action effect on the target request, which an agent would need to predict consequences.

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

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

Schema coverage is 75% and the description adds a genuinely useful detail not in the schema: action is case-insensitive. But the undocumented `shortId` required parameter gets no explanation in either place, and the description says nothing about how account/workspace interact with moderation calls.

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 set (approve/reject/mark spam) against a specific resource (feature request), which implicitly separates it from the sibling fr_moderate_bug. It does not name the sibling or the alternative status tooling (fr_set_request_status) explicitly, so differentiation is inferred rather than spelled out.

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 prerequisite 'Requires `Manage Queue` permission' and the API-key scope give actionable context, and case-insensitivity is noted. However, there is no guidance on when to use moderation versus fr_set_request_status, nor on when each action (approve vs reject vs spam) is appropriate.

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; the description adds genuinely new behavioral facts: the required API-key scope `feedback:bugs:write`, that emails resolve case-insensitively against workspace members, and the 400 on dual-assignment. Missing is what happens to the previous assignee (notification/replacement) and the success response, but the disclosure goes well past the annotations.

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

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

Three compact sentences, verb-and-resource first, then the parameter rule, then the auth scope — no filler and nothing that 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 single-purpose mutation with no output schema and annotations already covering safety, the description supplies the remaining decision-critical details: mutual exclusivity, unassign default, email resolution, and required scope.

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 critical cross-field constraint (exactly one of two assignee params, neither means unassign) cannot be expressed in this flat schema and is stated clearly, along with email resolution rules. shortId is left unexplained, but schema coverage at 60% handles account and workspace.

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

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

Opens with a specific verb pair (assign/unassign) and resource (bug), and the semantics of the two directions are stated immediately. An agent can distinguish this from fr_set_bug_status or fr_set_bug_visibility without reading any schema.

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

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

Gives explicit call-shape rules: supply exactly one of assigneeEmail or assigneeId, both yields 400, and neither unassigns. It does not contrast with sibling tools (e.g. status vs. assignee vs. visibility changes), 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?

The annotations already declare this as a destructive, non-idempotent, open-world mutation, so the safety profile is covered. The description adds useful behavioral context: status matching is lenient against the board's bug-status set and the required API scope is `feedback:bugs:write`. It does not explain reversibility or side effects beyond what annotations provide.

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

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

The description is two short, front-loaded clauses with no wasted text. The core action and matching behavior come first, followed by the API scope.

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

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

For a destructive mutation with annotations and no output schema, the description covers purpose and one important behavioral trait. However, it lacks usage guidance relative to siblings and does not explain the `shortId` parameter or the expected effect of the status change.

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

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

Schema description coverage is 50%; account and workspace are fully documented in the schema. The description adds meaning for the `status` parameter by specifying lenient name matching against the board's bug-status set, but it does not clarify `shortId` beyond its required status.

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

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

The description states a specific verb and resource: change a bug status by name. It also clarifies that matching is lenient against the board's bug-status set, which distinguishes it from a generic update. It does not explicitly contrast with sibling fr_set_request_status, but the bug-status wording is sufficiently 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 description says what the tool does but gives no guidance on when to use it versus alternatives such as fr_set_request_status. It also omits any prerequisites or conditions, aside from the API-key scope note.

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 openWorldHint=true, so the bar is lower. The description nonetheless adds genuinely non-obvious behavior — the security-bug invariant that overrides the caller's intent — and the required API-key scope (`feedback:bugs:write`), which is auth context the annotations do not carry.

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, front-loaded sentences with no filler; the action comes first, followed by the caveat, then the auth requirement. Only the backticked scope token is slightly noisy, but it carries real 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 destructive mutation with no output schema, the description covers purpose, one key invariant, and auth scope, but omits what happens when a security bug is targeted (silent no-op vs. error), whether related objects (comments, attachments, linked requests) change visibility, and how shortId is formatted. An agent could still call it, but not predict the outcome precisely.

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 only 50%: shortId and isPublic have no descriptions in the schema, and the description provides no meaning for either. Worse, 'toggle' suggests flipping current state while the required isPublic boolean implies setting an explicit target state — the description leaves that ambiguity unresolved, so it adds nothing and mildly misleads.

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: 'Toggle a bug's public visibility,' so an agent immediately knows this mutates visibility state rather than status, assignee, or content. It doesn't explicitly contrast with siblings like fr_set_bug_status or fr_set_bug_assignee, but the resource-level distinction is clear enough.

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 one real constraint — security bugs stay private regardless — which tells the agent this call may be a no-op for that class of bug. Beyond that there is no when-to-use guidance, no mention of prerequisites (e.g., ownership/moderation rights), and no named alternative for related visibility operations.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds valuable behavior beyond that: lenient status-name resolution via trim plus case-insensitive matching, the board-scoped status set, the returned updated request detail, and the required API-key scope. It does not explain failure behavior when the status name is invalid, but the annotation burden is already partly covered.

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

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

The description is three tight sentences with the main action front-loaded, followed by resolution behavior, return value, and auth scope. Every sentence adds useful information without repetition.

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

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

For a mutation tool with annotations covering the safety profile and no output schema, the description is largely complete: it states the action, status resolution behavior, return shape, and auth scope. Minor gaps remain around invalid-status handling and the undocumented shortId parameter, but nothing critical for invocation is missing.

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

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

Schema coverage is 75%, so the schema already documents account, workspace, and status. The description adds real semantic value for the status parameter by explaining that the name is resolved leniently against the request's board status set, going beyond the schema's simple example.

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: changing a feature request's status by name. The feature-request scope distinguishes it from the sibling bug-status tool, so an agent can identify the correct tool without inspecting schemas.

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

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

It implies the tool changes a status, but gives no explicit when-to-use guidance, prerequisites, or comparison to alternatives such as fr_set_bug_status. The API-key scope is useful context, but it is not usage guidance.

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

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

Annotations already declare the write/non-idempotent/destructive profile, and the description adds useful context: the return value (updated bug detail with new affectedCount) and the required API-key scope `feedback:bugs:write`. It does not explain the surprising destructiveHint for what is a reversible self-toggle, but the toggle semantics and scope disclosure are valuable additions.

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

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

Two tight sentences, front-loaded with the action and followed by the concrete return value and scope. Every clause earns its place.

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

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

No output schema exists, but the description states what is returned (updated bug detail + affectedCount). Scope is disclosed. The only gap is the undocumented `shortId` semantics, which slightly under-informs for the sole required parameter.

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

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

Schema coverage is 67%; account and workspace are richly documented in the schema, but required `shortId` has no description there and the tool description does not clarify its format or meaning either. Baseline 3 is appropriate given the partial schema coverage and minimal compensation.

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 (Toggle) plus specific resource (the caller's "I'm affected" marker on a bug). No sibling performs this operation (fr_vote_request votes, fr_get_bug reads), so an agent can distinguish it clearly 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?

The word "Toggle" implies the use case (flip your own affected state) and the on/off nature is conveyed. However there is no explicit when-to-use clause, no when-not, and no named alternative among siblings. Usage is implied rather than stated.

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

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

The description explicitly calls the operation an 'idempotent toggle', while the annotations set idempotentHint=false. That is a direct contradiction, and the description also does not reconcile destructiveHint=true, leaving the agent with conflicting safety and idempotency signals.

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

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

Three tight sentences front-load the action and toggle rule, followed by a useful API-key scope note. There is no wasted framing or repetition.

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

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

Covers the core toggle behavior and emoji/auth scope, but leaves return behavior unspecified despite there being no output schema. It also does not address the destructiveHint=true annotation, which matters for an agent invoking a 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?

Schema coverage is already 75%, and the schema documents account and workspace well. The description adds meaningful emoji semantics beyond the schema by explaining that null or omitted means plain upvote and that repeating the same emoji removes the vote.

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 ('Toggle') and resource ('vote or emoji reaction on a feature request'), and the plain-upvote distinction makes the scope concrete. It does not explicitly differentiate from nearby toggle-style siblings such as fr_toggle_bug_affected, 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?

Explains how to register a plain upvote (omit emoji or pass null) and that calling again with the same emoji removes the vote. This gives clear invocation context, but it does not name alternatives 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 readOnly/idempotent/non-destructive, so the bar is lower, and the description adds a genuine authorization disclosure: 'Discovery never grants access.' It also surfaces the fallback behavior. However, it says nothing about what the response shape or pagination looks like, so it's not fully complete.

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

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

Two compact sentences with no filler, front-loaded with the discovery purpose. The fallback sentence is slightly internal-context heavy against the little parameter value it adds, 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?

With 4 undocumented parameters, no output schema, and no per-parameter explanation, the description leaves too much for the agent to infer. It should explain how account/workspace/tag scope results and what 'tag schema' returns.

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 0% for 4 parameters, so the description carries the full burden but only implicitly covers two of them ('tags' for tag, 'one product' for service). The account and workspace parameters are undocumented in both schema and description.

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

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

States a specific verb (Discover) and resource (deployed API tags or a tag schema) for one product, which is clear enough that an agent knows what it retrieves. It doesn't name or differentiate itself from any sibling (e.g., get_endpoint_examples), so it stops short of full disambiguation.

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 ('Discover... for one product') and the required service parameter suggests scoping, but there is no explicit when-to-use vs when-to-use-alternative guidance. The 'prefers versioned... falls back only when unsupported' sentence describes internal catalog selection, not agent-facing routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds meaningful traits: the response is a catalog JSON with payloads at `operations[*].requestBodyExamples[name].value`, and that this tier carries the heavy payloads. It does not discuss auth or account/workspace selection, but the schema covers those.

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

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

Front-loads the purpose and the trigger condition, then parameter guidance, then the endpoint tier explanation. Dense and mostly earning its place, though the three-tier catalog recap at the end is slightly verbose for a tool the agent has probably already reasoned about.

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 five parameters, no output schema, and no truncation hints, the description supplies the missing return-shape information (the `operations[*].requestBodyExamples[name].value` path) and the narrowing strategy. Nothing needed to invoke it correctly is absent.

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

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

Schema coverage is 100%, so baseline is 3; the description goes further by giving concrete example values for tag ('Wiki Pages (Lite)'), operationId ('createPage'), and name ('full', 'full-tiptap') and explaining where those names come from (the per-tag detail response). This meaningfully supplements 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 ('Fetch the request/response example payloads ... for a Dutify API resource tag') and explicitly distinguishes itself from the sibling catalog tools get_api_catalog (tag list) and the per-tag detail endpoint, naming which tier it calls. An agent can tell exactly what this returns versus its neighbors.

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

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

Gives an explicit trigger condition ('when you're about to write rich content via a tool that accepts a TipTap content parameter, e.g. wiki_create_page'), names the lighter alternatives and when to use them, and explains how to narrow with operationId/name to avoid paying tokens for unused examples.

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; the description adds genuinely new context by disclosing the required recordings:write scope and the concrete consequence for the next regeneration. It omits what happens if no per-call prompt exists (error vs silent no-op), which matters given non-idempotency.

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

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

Three short sentences, front-loaded with the action and scope, then consequence, then auth requirement — no filler or repetition of structured fields.

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-target removal with no output schema, the description covers purpose, sibling scoping, downstream effect, and auth requirement — 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%, so the id, account, and workspace parameters are fully documented in the schema. The description adds nothing about them; baseline 3 applies since the schema does all 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?

States a specific verb ("Remove") and a precisely scoped resource ("the caller's own per-call prompt"), which implicitly separates it from the event- and series-level clear siblings. It stops short of naming those siblings, but the "per-call" qualifier does the discrimination work.

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

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

The description explains the downstream effect (the next hub_regenerate_summary falls back to the instruction set), which implies usage context, but never states when to call this versus hub_set_call_custom_prompt or the event/series variants, and gives no prerequisites beyond scope.

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 structurally. The description adds genuinely non-obvious behavioral context: clearing the occurrence prompt does not cause a fallback to anything, because the series prompt was already in effect, plus the recordings:write authorization requirement. It stops short of saying whether clearing a non-existent prompt errors or how to restore it.

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

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

Two sentences, front-loaded with the action, second sentence devoted entirely to the one non-obvious semantic point (no fallback) and the scope requirement. No filler and nothing repeated from the schema.

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

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

Clear and complete for a deterministic operation whose three parameters are fully documented in the schema and whose safety profile is in annotations. The one thing an agent could get wrong here — assuming the series prompt disappears too — is explicitly addressed.

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 account, eventId, and workspace all documented in the schema itself (including the eventId pointer to hub_list_calendar_events). The description adds nothing about parameter formats, so the baseline 3 applies rather than a higher score.

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 ('Remove') and a precise resource ('one occurrence's own prompt'), and implicitly separates it from the series-level siblings by noting the series prompt is untouched. It never names the sibling tools (hub_clear_series_custom_prompt, hub_clear_call_custom_prompt) explicitly, and 'occurrence' is never mapped back to 'event', so the tool name has to do some work.

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 clarifies the outcome of clearing (series prompt continues to apply) which implies the use case: removing a per-occurrence override only. However, it gives no explicit guidance on when to choose this over hub_clear_series_custom_prompt or hub_clear_call_custom_prompt, and no note on prerequisites beyond the scope requirement.

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 destructive flag, but the description adds genuine context beyond them: the auth requirement ('Requires recordings:write scope'), the consequence to other occurrences ('drops instructions every other occurrence relies on'), and the post-state ('Each occurrence keeps only its own prompt'). This is exactly the extra context annotations can't convey.

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

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

Front-loads the core action, then the misuse warning, then the scope requirement. Every sentence earns its place with no filler; the caution sentence justifies its length by preventing a costly error.

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

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

For a destructive mutation with no output schema, the description covers effects on occurrences, the auth requirement, and the misuse risk. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the schema fully documents seriesMasterId, account, and workspace. The description adds no parameter-specific syntax or format detail 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 ('Remove') and resource ('a series' custom prompt'), clearly distinct from sibling setters like hub_set_series_custom_prompt and from the call/event variants. An agent can identify the operation without opening the schema.

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

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

Provides an explicit anti-pattern ('Never clear a series prompt to avoid a conflict...') that steers correct usage, and clarifies the relationship with occurrence prompts. It lacks an explicit pointer to alternative tools (e.g., set, or clearing occurrence prompts), but the when-not guidance is unusually strong.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description's real contribution is the auth requirement ('Requires recordings:read scope') and the permission-scoped visibility of the count. Both are operationally useful and not derivable from annotations or schema. Return shape (bare integer vs envelope) is left unstated.

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

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

Three short sentences, purpose first, usage second, prerequisite last. No filler and nothing repeated from the title or schema.

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

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

A simple zero-required-parameter read tool with full schema coverage and no output schema; the description says what is returned (a total) and what scope governs it. Slightly short on whether the count respects the workspace/account selection, but nothing blocking an agent from calling 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% with rich per-parameter text for account and workspace, so the baseline is 3. The description adds nothing about how workspace scoping affects the returned total, which is the one genuinely non-obvious semantic here.

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

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

Specific verb+resource ('Return the total number of calls') with an explicit scope qualifier ('visible to the actor user'), which implicitly separates it from hub_list_calls and hub_count_search_calls. It never names those siblings outright, so the differentiation is inferred rather than stated.

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

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

'Use to plan pagination' gives a concrete when-to-use condition, which is the main reason an agent would reach for a count endpoint. It stops short of explicit exclusions (e.g. 'do not use to count filtered results — use hub_count_search_calls') or prerequisite ordering.

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 (readOnly, idempotent, non-destructive), yet the description still adds a real operational prerequisite: 'Requires recordings:read scope.' That auth requirement is exactly the kind of context annotations don't carry. It omits whether the count is exact vs. capped for very large result sets.

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 filler; the core purpose leads, the sibling pairing follows, and the auth prerequisite closes. Nothing could be removed 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?

No output schema exists, yet the description says nothing about the shape of the result (raw integer? object with a count field?) or whether the count is bounded for large result sets. For a minimal tool with rich schema coverage this is adequate, but the return-value gap is real when there is no output schema to fall back on.

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%, including detailed account and workspace semantics, so parameter meaning is fully handled by the schema. The description only echoes 'search query' without adding format or matching-behavior detail, 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 ('Count') and resource ('calls matching a search query'), so the agent knows exactly what it returns. It implicitly separates itself from hub_search_calls by pointing at it as the paginated companion, but never explicitly contrasts with the sibling hub_count_calls (count of all calls), which an agent could easily confuse with this tool.

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?

'Pair with `hub_search_calls` for paginated UIs' gives a concrete usage pattern and names the alternative tool to combine with. It stops short of when-not-to-use guidance (e.g., use hub_count_calls when you have no query filter), so the routing signal is clear but incomplete.

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?

Although annotations already mark the tool as destructive, the description adds crucial details: both metadata and recording media are hard-deleted, the operation is NOT REVERSIBLE, and the recordings:write scope is required. This is exactly the behavioral context an agent needs before invoking a destructive tool.

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

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

The description is four short sentences with zero waste. The destructive scope and irreversibility warning are front-loaded immediately after the core action.

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 rich schema descriptions, destructive annotations, and absence of an output schema, the description supplies all the missing high-value context: what is deleted, that it is irreversible, and the required authorization scope.

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 fully documents id, account, and workspace. The description only restates that deletion is by ID and adds no additional parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource: delete a call by ID. It also specifies that both UserCall metadata and the underlying recording media are hard-deleted, making the operation clearly distinct from read-oriented siblings such as hub_get_call.

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 strong caution to use with care and states the required recordings:write scope. It does not explicitly compare this tool with alternative cleanup or mutation siblings, but the context for use is otherwise 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuine behavioral context beyond that: the URL is short-lived, defaults to 30 minutes, the max is enforced server-side by Hub, and it must not be cached. It stops short of failure modes (e.g., what happens if the recording has no audio yet).

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 with no filler, front-loaded with the core action and followed by expiry semantics and the caching warning. 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?

With no output schema and full parameter coverage, the description sufficiently explains what is returned (a signed download URL), its lifetime, and the auth requirement. The only notable omission is error/precondition behavior when audio is unavailable.

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 recordingId and expiryMinutes are already documented in the schema, and the description largely restates the 30-minute default. It only marginally adds value by noting the max expiry is enforced by Hub. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: generate a short-lived signed URL for a recording's audio, even noting typical formats (MP3/WAV). It is clear what the tool returns, but it never distinguishes itself from close siblings like hub_get_media_url or hub_get_preview_url, leaving the agent to infer which URL variant it wants.

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

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

It gives a clear operational directive (do not cache, request fresh each time) and states the required recordings:read scope, which is real usage guidance. However, it never says when to prefer this over the sibling URL tools (media/preview), so the alternatives question is left unanswered.

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 adds substantial behavioral context beyond the annotations: it names the returned DTO, maps nested fields to their meanings and intended API use, clarifies that summary fields are markdown strings rather than arrays, notes that userNotes are caller-only, and states the required recordings:read scope. This is especially valuable because there is no output schema.

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

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

The description is front-loaded with the core action and then uses a structured field map for the nested DTO. Despite its length, every bullet earns its place because the return shape is complex and there is no output schema to document it.

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 deeply nested UserCallDTO and the absence of an output schema, the description provides the field interpretation an agent needs to use the result correctly. It also covers the authorization scope, making the definition complete for this retrieval 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 id, account, and workspace parameters are already documented in the schema. The description reinforces that the tool takes a call ID, but it does not add new parameter-level guidance beyond what the schema already provides; its detail is focused on returned fields.

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

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

The description opens with a specific verb and resource: fetching a single call by ID, returning the full UserCallDTO. It clearly distinguishes retrieval-by-ID from list/search siblings through the ID-based framing and provides a detailed field map of what will be returned.

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

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

It clearly establishes that this tool is used when retrieving one call by its ID and states the required recordings:read scope. It does not explicitly compare against alternatives like hub_search_calls or hub_list_calls, but the context is sufficiently clear for an agent to select the right tool when an ID is available.

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 and closed-world, so the safety profile is covered; the description adds genuinely useful non-schema context: the required workspace-settings:read scope and the fact that customPrompt may be null. It does not describe failure modes for insufficient scope, but the added auth and nullability detail clears the bar for annotations-present tools.

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

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

Front-loaded with the verb and resource, and every clause carries information (instruction-set composition, return shape, scope requirement). The middle clause is long and parenthetical-heavy, making it denser than needed, but there is no filler.

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

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

There is no output schema, and the description compensates by declaring the exact return type including nullability. Combined with the auth scope and the explanation of how the value is consumed, an agent has everything needed to call and interpret this 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% and both the account and workspace parameters are thoroughly documented in the schema, including multi-account fallback behavior and workspace override rules. The description adds nothing about parameters, which is acceptable here but caps it at the baseline.

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

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

States a specific verb and resource ("Get the workspace's custom prompt") and immediately defines what that resource is — house-style instructions feeding summary/key-point/action-item/enhanced-note generation. It also states the return shape, and the phrase "each participant's own per-call prompt" implicitly separates it from the per-call sibling tools.

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

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

The description gives solid context about what the value is and what consumes it, which implies when an agent would want it (inspecting house style before setting or reasoning about generated summaries). However, it never names an alternative explicitly or states a when-not condition versus hub_get_workspace, hub_set_custom_prompt, or find_my_workspace — usage must be inferred.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new context beyond them: the nullable return shape ({ workspaceId: uuid | null }) and the required user-settings:read scope, which tells the agent an auth precondition exists.

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

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

Three compact clauses, front-loaded with the action and its meaning, then the return shape, then the scope requirement. No filler and nothing repeated from the schema.

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

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

With no output schema present, the description steps in to state the return shape and nullability, plus the auth scope — the two things an agent would otherwise have to guess. Minor gap: no guidance on the account/workspace parameters or what a null result means operationally.

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?

Both parameters are optional and documented at 100% schema coverage, including the multi-account failure mode (ACCOUNT_REQUIRED) and workspace override semantics. The description adds nothing about them, but with full schema coverage 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?

A specific verb+resource ('Get the user's default workspace') with an added functional gloss explaining what the default workspace actually controls (routing of unassigned calendar events). It does not, however, distinguish itself from the nearby sibling find_my_workspace or from hub_get_workspace, which an agent could easily conflate.

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 through the routing explanation (call this when you need to know where unassigned events land), but there is no explicit when-to-use/when-not framing and no mention of the obvious alternative find_my_workspace or of the write counterpart hub_set_default_workspace.

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

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

Annotations already cover safety (readOnly, non-destructive, idempotent), and the description adds genuinely new behavior: automatic degradation to audio-only when no video track exists, shared expiry semantics with the audio tool, and the recordings:read authorization requirement. What it omits is the concrete return shape (e.g. whether the response includes an expiry timestamp alongside the URL).

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 filler, led by the differentiation that matters most. Each sentence carries distinct information: what differs from the audio tool, the fallback, and the auth prerequisite.

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 URL-returning read with no output schema, the definition covers purpose, sibling choice, fallback behavior, expiry and scope. The remaining gap is return-value shape (URL field name, whether expiry is returned), which an agent would have to infer.

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 account, workspace, recordingId and expiryMinutes are already documented in the schema. The description only gestures at expiry ('Same expiry semantics') without restating the parameter or its default, 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 (get media URL) and explicitly anchors it to a named sibling, hub_get_audio_url, contrasting the two: this returns video+audio when a video track exists, audio-only otherwise. An agent can distinguish it from hub_get_audio_url and hub_get_preview_url 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?

The 'Like X but...' framing gives a clear selection rule: choose this over the audio-only tool when full media is wanted, with the fallback stated as automatic. It also names the required recordings:read scope. It does not spell out an explicit when-not case (e.g. when to prefer hub_get_audio_url instead), keeping it just short of 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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the explicit "Requires workspace-settings:read scope" auth requirement and the interpretation of the returned value as the default routing target.

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

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

Two compact clauses: the core purpose is front-loaded, and the scope prerequisite follows as a short separate statement. Every sentence earns its place with no filler.

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

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

For a no-argument read with full schema coverage and read-only annotations, the description supplies everything needed to call it correctly: what it returns conceptually and what permission is required. Only the shape of the returned value (e.g., whether it includes an integration id versus just a name) is left implicit, which is minor given no output schema exists.

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

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

Schema description coverage is 100% and both parameters (account, workspace) carry detailed inline documentation, so the schema already does the heavy lifting. The description says nothing about how account or workspace selection interacts with this call, leaving it at the baseline.

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

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

The description uses a specific verb ("Get") on a specific resource ("workspace's preferred integration target") and immediately explains what that concept means: the task system new actions route to by default, with concrete examples (Jira, ClickUp, Airtable, PM). This clearly distinguishes it from the sibling hub_set_preferred_integration and from hub_list_integrations.

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 read-only nature and the mentioned scope imply when the tool applies, but the description never states the condition for calling it versus alternatives — notably the setter sibling hub_set_preferred_integration or hub_list_integrations for enumerating available targets. Usage must be inferred from the name and the verb.

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 establish the safe read-only, idempotent profile. The description adds genuinely new context: the URL is signed, requires the recordings:read scope, and expires. That scope requirement in particular is not derivable from annotations or schema. It doesn't state the URL's eventual failure mode when expired, keeping it at 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 short sentences, front-loaded with the core action and asset type, no padding. 'Same expiry semantics' is a dangling reference that assumes the reader has just seen a sibling definition, a minor structural flaw.

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 does state the return value (a signed URL) and its auth scope, and all four parameters are schema-documented. An agent could call this correctly; only the expiry default and the expected error on an expired URL are left implicit.

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 recordingId, account, workspace and expiryMinutes are already documented in structured form. The phrase 'Same expiry semantics' gestures at expiryMinutes but adds no detail beyond the schema's 'Default 30', so baseline 3 is correct.

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

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

States a specific verb and resource ('Get a signed URL for the recording's preview thumbnail') and immediately clarifies what the asset is (still image or short looping clip). It implicitly differentiates from hub_get_audio_url and hub_get_media_url by naming the preview thumbnail, though it never names those siblings explicitly.

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

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

'Useful for embedding a card' gives one positive use case, which is more than nothing. But there is no explicit routing guidance to hub_get_media_url or hub_get_audio_url, and no statement of when this tool is not appropriate.

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 the description adds value beyond them: the concrete return shape (integer 0-100) and the required recordings:read scope. It omits edge behavior such as what is returned or raised if the recording id doesn't exist or has never been processed, 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?

Three tight sentences: purpose first, return contract second, auth prerequisite last. No filler and nothing 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 no output schema, the description carries the return contract and does so (integer 0-100), and the one required parameter is schema-documented. A small gap remains around terminal states and error conditions, but an agent has enough 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 description coverage is 100%, so account, workspace and recordingId are all documented at the schema level. The description adds nothing about parameters 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 ('Get the processing progress of a recording') and immediately pins down the returned value range 0-100, so an agent knows exactly what this yields. It does not explicitly distinguish itself from hub_get_call, which likely also exposes recording state, so sibling differentiation is only partial.

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 usage context — polling after a hub_reprocess_recording call — which names the sibling it pairs with and the temporal ordering. It stops short of saying when not to use it (e.g., when the recording is already processed, or to use hub_get_call for full detail) or how often to poll.

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/no-destructive, so the bar is lower, and the description adds real value: it discloses the "workspaces:read" scope requirement and the implementation caveat that no single-workspace GET exists so it filters the user's workspaces list. That caveat explains result semantics an agent would otherwise misread.

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 core action and scope requirement bookend the description efficiently. The stacked parenthetical about workspace keys is slightly hard to parse but does not waste sentences.

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 wisely tells the agent the return value is the matching entry from the workspaces list (so shape matches list_workspaces). Auth scope, selection semantics, and the sibling-driven discovery path are all covered; only an explicit pointer to hub_get_default_workspace is missing.

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

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

Schema coverage is 100%, so both account and workspace are fully documented in the input schema, including override and multi-account failure behavior. The description adds no syntax or selection detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb+resource ("Get details for the selected workspace") and scopes it to either the selected workspace or the key-bound workspace. The note that it returns the matching entry from the user's workspaces list effectively distinguishes it from list_workspaces, though it never names a sibling directly.

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

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

Implies when to use it (you want details on the current/selected workspace) but gives no explicit when-not guidance or routing to hub_get_default_workspace or list_workspaces. The useful discovery hint ("discover candidates with list_workspaces") lives only in the parameter schema, not the description.

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 adds genuinely useful behavior facts beyond the annotations: 15-30s synthesis latency, a deliberately generous MCP timeout, and the required lens:chat scope. However, it describes a knowledge query that 'returns the synthesized answer as a string', which reads as a pure read, while annotations declare readOnlyHint=false and destructiveHint=true. The description never reconciles that mismatch, so an agent cannot tell why this call would be considered destructive or what state could change.

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 purpose and return value, then parameters, then operational caveats (latency, timeout, scope) — a sensible order with little waste. The sentence 'Pass `lastMessage` ... and optionally `history`' largely restates the required/optional schema and could be folded into the multi-turn guidance.

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 four-parameter, output-schema-less tool the description covers what is returned (a string), the multi-turn contract, latency, and auth scope, which is close to enough to invoke it correctly. The remaining hole is behavioral: nothing explains the destructive/non-idempotent annotations, leaving an unexplained safety profile on what appears to be a read-style query.

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 3 is the baseline, and the description goes beyond it by framing `lastMessage` as 'the new user turn' and `history` as accumulating prior turns whose purpose is reference resolution. That is semantic value the schema's field-level docs do not convey, though the `account`/`workspace` auth semantics are left entirely to 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 ('Run a Lens chat query against the workspace's knowledge') and lists the covered data sources (recordings, calls, transcripts, SaaS data), plus what it returns (a synthesized answer string). It implicitly separates itself from retrieval-style siblings like hub_search_calls, but never names an alternative, so the differentiation is inferential rather than explicit.

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

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

Gives clear invocation guidance: pass `lastMessage` as the new turn, pass `history` for follow-ups, and explicitly tells the agent it SHOULD accumulate history so Lens can resolve references like 'the last call we discussed'. What is missing is when NOT to use it — e.g. when to prefer hub_search_calls or hub_get_call over a synthesized chat answer.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the burden is reduced; the description still adds real value by disclosing the required calendar:read scope and the ownership model ('events belong to the user across all workspace assignments'). It does not mention result caps or pagination, which is the main 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?

Four sentences, front-loaded with purpose, then usage, then return contents, then scope/auth. No filler, and the reader's most important question (what do I get back) is answered before the operational caveats.

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 returned fields (subject, start/end, recording-bot subscription, event/series custom prompts). Combined with the ownership and auth notes, 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 coverage is 100%, so the baseline is 3, but the description adds non-obvious semantics for `workspace`: it is processing context, not an ownership filter, so passing it will not narrow results. That clarification meaningfully changes how an agent uses the parameter.

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, and scope: 'List the actor user's calendar events in a date range.' It is unmistakably distinct from the hub_list_calls / hub_search_calls siblings that operate on calls rather than calendar events.

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

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

'Use this to find the eventId or seriesMasterId a prompt should attach to' gives a concrete selection context that routes the agent toward the hub_set_event_custom_prompt / hub_set_series_custom_prompt family. It stops short of naming an explicit alternative or a when-not-to-use case, so it falls just below the top band.

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 (readOnly, idempotent, non-destructive, closed-world), so credit goes to what the text adds: the visibility model (own + explicitly shared), sort order (most-recent first), pagination style, and the required recordings:read scope. That is real authorization and result-shape context beyond the annotations.

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

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

Three short sentences, all front-loaded: scope first, return type second, pagination/sort/auth third. No filler and nothing structural is missing.

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/list tool with full annotation and schema coverage, this covers visibility scope, pagination, ordering and required scope. The only gap is that 'UserCallDTO' is referenced without saying what fields matter to a calling agent.

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 page, size, account and workspace are fully documented in the schema. The description only restates 'pagination is page+size' and adds nothing about the account/workspace selection parameters. 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?

Specific verb + resource + visibility scope: 'Page through all calls the actor user can see (their own + any explicitly shared)'. An agent can distinguish this list-all tool from hub_search_calls conceptually, 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 implied by 'all calls ... can see' (unfiltered listing) versus the search siblings, but the description never states when to prefer hub_search_calls, hub_count_calls, or hub_get_call, nor any exclusions. Guidance must be inferred.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds the auth scope requirement and the per-toolkit result granularity, which an agent cannot infer from the schema. It doesn't mention ordering, pagination, or what an empty result means, so it falls short of a 5.

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

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

Three sentences, front-loaded with the operation, then the return contents, then the purpose and the auth prerequisite. Every clause carries information; no filler or restatement of 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?

With no output schema, the description correctly compensates by enumerating the returned fields, and it names the required scope. Minor gap: nothing about ordering, result limits, or behavior when no integrations are connected for a read-only list of unbounded size.

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 documented, and the description only loosely reinforces `workspace` ('the selected workspace, or the workspace bound to a workspace key'). The `account` parameter is never addressed in the description. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List all integrations connected to the selected workspace') plus the exact return shape: one entry per connected toolkit with system name, status, last sync time, and vendor metadata. This is clearly distinguishable from hub_get_preferred_integration/hub_set_preferred_integration 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?

Gives concrete use cases: discovering which value is valid for `setPreferredIntegration`, and reporting connection health to the user. It also states the required `integrations:read` scope. What's missing is an explicit exclusion (i.e. 'use hub_get_preferred_integration when you only need the single active one'), which would make routing 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond them: the members:read scope requirement, how the workspace is resolved (configured workspace vs. workspace-key binding), and the shape of each returned entry.

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 and scope, with the field list and scope requirement following. The quoted example phrasings are slightly informal but earn their place as usage cues.

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 compensates by enumerating the returned fields (UUID, email, name, role, join timestamp) and stating the auth scope. It is complete enough to invoke correctly; only return-volume/pagination behavior is unaddressed.

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

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

Schema coverage is 100% and both parameters are richly documented in the schema, so the baseline is 3. The description's note about the selected workspace vs. workspace-key binding marginally reinforces the workspace param but says nothing about the account parameter or its ACCOUNT_REQUIRED failure mode.

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 all members") plus the exact scope (selected workspace or workspace bound to a key), and enumerates the returned fields. This is clearly distinguishable from sibling listing tools such as pm_list_workspace_members or hub_get_workspace.

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 usage contexts ("tag this person", "summarize who said what in the last call") and states the required members:read scope, which is a real gating condition. It does not name an alternative tool or say when not to use it, so it stops short of full routing guidance.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds real value on top by bounding the blast radius ('other participants' versions are never touched'), naming the write scope required ('Requires recordings:write scope'), and disclosing what inputs drive the regeneration (current workspace prompt, per-call prompt, notes, note template). A small gap: it never says outright that the caller's existing summary is replaced/overwritten by the new one.

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, and each clause carries information (scope, inputs, cost comparison, return value, auth). Dense parenthetical enumerations ('workspace prompt, per-call prompt, notes and note template') make it slightly heavy, but nothing is 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 4-parameter mutation with no output schema, the description covers the essentials: it states the return value ('the new summary text'), the required scope, and the isolation guarantee. It does not address whether regeneration is synchronous/long-running or what happens on failure, which would matter for a reprocessing call.

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

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

Schema description coverage is 100%, so account/workspace/saveToDb/recordingId are all documented structurally; baseline 3 applies. The description adds behavioral rather than parameter-level meaning — it explains which instruction sources feed the run, but says nothing about saveToDb preview behavior or workspace selection that the schema doesn't already cover.

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 ('Re-run the analysis') and precisely scoped resource ('the CALLER's own version of the summary, key points, action items, enhanced notes'), with the negative scope stated explicitly ('Other participants' versions are never touched'). It is also unambiguously distinguished from the closest sibling, hub_reprocess_recording.

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 positions itself against the alternative by stating it is 'Cheaper than hub_reprocess_recording', and clarifies the scope condition (caller's own version only, enhanced notes only when notes exist). It stops short of stating the inverse condition — when an agent should choose hub_reprocess_recording instead (e.g., to touch other participants' versions).

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 valuable context beyond the annotations: cost/latency tradeoff, the recordings:write scope requirement, and that it returns an updated recording DTO. Annotations already declare destructiveHint=true and idempotentHint=false, but the description does not explicitly warn that the prior transcription and derived artifacts are replaced — a meaningful gap for a destructive re-run.

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, front-loading what the tool does and immediately routing to the alternative. Every sentence carries distinct information (scope, cost, selection criteria, return/scope requirements) with no filler.

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

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

No output schema exists, but the description states it returns the updated recording DTO plus the required scope. For a 4-parameter mutation with full schema coverage and rich annotations, nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so `account`, `workspace`, `regenerate`, and `recordingId` are already fully documented, which sets the baseline at 3. The description implies the pipeline stages affected but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (re-run) and the exact resource scope (FULL pipeline: transcription + summary + key points + action items) on a recording. It explicitly contrasts with the sibling `hub_regenerate_summary`, so an agent can distinguish them without opening either schema.

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

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

Names the cheaper alternative (`hub_regenerate_summary`) and gives the precise condition for choosing this tool instead: when a fresh transcription would meaningfully improve results, with concrete triggers (language detection, diarization fixes). This is explicit 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: the required recordings:read scope and that results are paginated. It does not mention rate limits or whether transcript matching is slower, but for a read tool 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?

Three short sentences, front-loaded with what is searched followed by return shape and auth prerequisite. No filler and nothing repeated from the schema.

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

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

With no output schema, naming UserCallDTO and pagination is a reasonable signal of the return shape, and the auth requirement is stated. Minor gaps remain around result ordering and whether transcript search is best-effort, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so page, size, query, account, and workspace are already fully documented in the schema. The description adds only that the query matches transcript content, which mildly clarifies query semantics but nothing about paging or multi-account behavior 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 (free-text search) and resource (calls), and enumerates the searched fields (name, description, attendees, transcript) plus the return type. It does not explicitly distinguish itself from hub_list_calls or hub_count_search_calls, so an agent must infer the difference from the word 'search'.

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: 'free-text search' suggests use when you have keywords, and the schema note 'Empty string lists all' hints at the list-like fallback. There is no explicit when-to-use or when-not, and no routing to hub_list_calls or hub_count_search_calls for the count-only or unfiltered 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 flag destructive=true, non-idempotent and open-world, so the safety profile is covered. The description adds materially beyond that: the auth/scope requirement and the crucial caveat that a boolean response means 'request accepted', not 'actually pushed' — a behavior an agent would otherwise misread as success. It doesn't explain why it's destructive (e.g. row creation vs overwrite) or what happens on repeated pushes despite idempotent=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?

Three tight sentences: action first, prerequisites second, return-shape caveat last. Every sentence carries distinct information and nothing is padded.

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

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

With no output schema, the description does the important work of explaining what the return value does and does not mean. For a destructive, non-idempotent write tool it could still say more about duplicate pushes or failure modes, but an agent has enough to call it correctly 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%, so baseId, tableIds, callUUID, account and workspace are all documented in the schema itself. The description only restates the cardinality constraint ('one base + one or more tables'), adding marginal value. Baseline 3 is appropriate.

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

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

States a specific verb ('Push') plus the exact resource and shape ('a call's extracted tasks into Airtable rows under one base + one or more tables'). The Airtable target distinguishes it cleanly from hub_send_call_to_jira and hub_send_call_to_clickup without needing to open either schema.

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

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

Gives concrete prerequisites (recordings:write scope AND a workspace Airtable integration), which is real selection guidance for a connector tool. It stops short of an explicit 'use this when the user wants Airtable rather than Jira/ClickUp' statement, so there's a small gap versus 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 destructive=true, idempotent=false and openWorld=true; the description adds real value on top by disclosing the misleading boolean return ("request accepted", not "actually pushed") and the auth/scope requirement. It stops short of warning that re-invoking creates duplicates despite non-idempotency, which is the main operational risk.

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 preconditions, then the return caveat. Slightly weakened by making the key caveat a cross-reference that only makes sense if the Jira tool's description was read.

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 partially compensates by characterizing the response as a boolean acceptance. But for a destructive, non-idempotent push it omits duplicate-creation behavior on retry and what fields/tasks get transferred, leaving meaningful gaps for the calling agent.

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%, including nested-location hints (`hub_get_call.call.callUuid`) and account/workspace semantics, so the schema carries the parameter burden. The description adds nothing parameter-specific — notably it does not say how to obtain a valid `selectedListId` (e.g., via list_spaces/list_boards).

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 ('Push a call's extracted tasks into a ClickUp list') and implicitly distinguishes itself from the sibling send targets (Airtable, Jira) by naming the destination. The explicit reference to `hub_send_call_to_jira` further anchors it within its tool family.

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 preconditions — requires `recordings:write` scope and a ClickUp integration on the workspace — which is more than most siblings offer. It does not, however, state when to prefer this over the Airtable/Jira variants or what to do if the integration 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?

Goes well beyond the annotations by disclosing that the vendor push is async, that true only means Hub ACCEPTED the request, that bad cloudId/project/expired tokens fail silently, and how to confirm actual landing. This directly addresses the high-risk behaviors annotations cannot express for an openWorld, non-idempotent write.

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, then requirements, then the critical boolean-semantics warning last. Every sentence carries actionable information with no filler.

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

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

With no output schema, the description crucially fills in the return-value semantics (boolean = accepted, not landed) and the async silent-failure risk. Combined with prerequisites and verification steps, an agent has everything needed to call and validate 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 is detailed, so the baseline is 3. The description adds one useful constraint — that all projectIds must be under the same cloudId and are fanned out — but otherwise defers to the schema for parameter meaning.

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

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

The description states a specific verb and resource: push a call's extracted tasks into one or more Jira projects under the same cloud. The destination (Jira) cleanly distinguishes it from hub_send_call_to_airtable and hub_send_call_to_clickup without opening either schema.

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

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

It names the prerequisites (recordings:write scope AND a Jira integration) and points to hub_list_integrations to satisfy them, plus explains how to verify landing via hub_get_call. It doesn't explicitly say when not to use it versus the airtable/clickup siblings, but the destination makes the choice self-evident.

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 the write/destructive nature; the description adds genuinely non-obvious behavior: the write is stored but does not itself re-analyse, the prompt is caller-scoped and affects only that user's summary/key points/action items/notes, and the call needs recordings:write scope. Those facts are not derivable from the structured fields.

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

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

Four short sentences, front-loaded with the action and identifier, then the differentiating scenario, then the effect scope, then the follow-up and auth requirement. No sentence is 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?

Covers purpose, scoping, follow-up and required scope for a mutation tool with no output schema. It stops short of stating what happens when a custom prompt already exists (overwrite vs. error) despite destructiveHint=true, which is the one behavioral detail an agent would still want.

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, and the description adds real meaning by explaining what customPrompt actually controls (the caller's own summary, key points, action items, enhanced notes) and that id is an integer UserCall id. It does not add anything about the account/workspace scoping parameters, which the schema already handles.

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 ("Set the custom prompt on an already-recorded call") with the identifier type. It also carves out the sibling boundary by naming the exact scenario (ad-hoc desktop/bot recordings without calendar events) that separates it from hub_set_event_custom_prompt and hub_set_series_custom_prompt.

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

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

Gives concrete use cases (meetings with no calendar event, re-analysing a call differently) and states the required follow-up step: "Stored only — follow it with hub_regenerate_summary to rebuild that version." An agent knows both when to reach for this and what to do next without inferring from sibling names.

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 destructive/open-world annotations, the description adds useful behavior: passing null or empty clears the prompt, the change only affects the next processed recording, and existing recordings are not re-analysed automatically. It also names the required write scope.

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 core action and packed with timing, clearing, and scope details. There is no wasted language.

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 rich annotations and fully described parameters, the description covers the important gaps: how to clear, when the change applies, and the required permission. No output schema is needed for this setting update.

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 account, workspace, and customPrompt are already well documented. The description adds that an empty string also clears the prompt, but otherwise relies on the schema for parameter meaning.

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

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

The description states a specific verb and resource: update the workspace's custom prompt. The word 'workspace's' distinguishes this from the sibling call-, event-, and series-level custom prompt setters.

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

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

It explains when the change takes effect and points to hub_regenerate_summary for existing recordings, giving a clear alternative for that case. It does not explicitly compare against the call/event/series custom prompt tools, but the workspace scope is clearly 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 cover destructive/openWorld/non-idempotent, but the description adds substantial context beyond them: what the default actually controls, that the MCP auto-fills the UUID, that a different workspace cannot be targeted, and the required user-settings:write scope. It stops short of saying the previous default is overwritten, which is the main thing destructiveHint=true implies.

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

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

Three tight sentences: the action and its effect first, the clearing escape hatch second, the auto-fill constraint third, with the scope requirement last. No sentence is redundant and nothing important 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?

For a 3-parameter, zero-required mutation with no output schema, the description covers effect, alternatives, constraints and auth scope. There is no return value to document and no meaningful gap an agent would need filled before calling.

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 would be 3, but the description earns extra credit by clarifying semantics the schema cannot: the workspace UUID is filled automatically and cannot be aimed at another workspace from this key, so the 'workspace' parameter is effectively informational. It also explains the clear flag's effect in business terms.

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 ("Set the user's 'default workspace'") and immediately states the observable consequence (future calendar events without an explicit workspace route there). That distinguishes it cleanly from hub_get_default_workspace and the other hub_set_* tools without needing the schema.

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

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

It gives a clear when-to-use condition (routing future calendar events) and an explicit alternative path for the opposite intent ("To clear the default entirely, pass { clear: true }"). It also states a hard constraint (agents cannot target a different workspace from this key). What's missing is a pointer to hub_get_default_workspace for reading the current value or to list_workspaces for discovery.

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 beyond the annotations by disclosing that the change is deferred ('takes effect the next time that meeting is processed') and that recordings:write scope is required — neither is derivable from destructiveHint/openWorldHint. It does not say whether an existing per-event prompt is overwritten or how to revert, which matters given destructiveHint=true.

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, scope constraint front-loaded in the first, with no filler. Every clause (composition, timing, auth scope) conveys callable 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?

Covers the essentials for a mutation tool: what it targets, how it composes with existing prompts, when it takes effect, and the auth scope. The only gap is overwrite/clear behavior, which is partly covered by the sibling hub_clear_event_custom_prompt.

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 account, eventId, workspace and customPrompt are already documented in the schema. The description adds only the implicit 'one occurrence' framing for eventId; 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?

States a specific verb and resource ('Set the custom prompt for ONE calendar occurrence') and immediately scopes it against the series-level and workspace-level prompts, so an agent can distinguish it from hub_set_series_custom_prompt and hub_set_custom_prompt without opening schemas.

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

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

Explains the composition semantics for a series occurrence versus a one-off meeting, which tells the agent when this tool is the correct or only target. It stops short of explicitly naming the sibling alternatives (series/workspace/clear-event tools) or stating how to remove a prompt, so it is clear context without full routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=false and openWorldHint=true; the description usefully adds the auth scope requirement. However, for a tool flagged destructive it does not disclose what the write replaces — whether the prior preference is overwritten, whether the change is workspace-wide for all members, or what happens on an invalid integration name.

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

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

Two sentences, front-loaded with the action, then the value source and auth requirement. No filler and nothing 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?

Covers purpose, valid value source and permissions, which is the core an agent needs. It omits the mutating side effects implied by destructiveHint=true and any error behavior for unrecognized integration names, which matters for a write tool with no output schema.

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

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

Schema coverage is 100%, so all three parameters are already documented in the schema, including the same 'as returned by hub_list_integrations' note for preferredIntegration. The description adds only concrete example values (JIRA, CLICKUP, AIRTABLE, PM), which is marginal added value over the schema — baseline 3.

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

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

States a specific verb and resource: 'Set the workspace's preferred integration target.' The complement relationship with hub_get_preferred_integration and hub_list_integrations is inferable from the verb and the cross-reference, though neither sibling is named explicitly as an alternative.

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 preconditions: the value must come from hub_list_integrations and the caller needs workspace-settings:write scope. It does not state when-not to use it (e.g. single-integration or read-only contexts), so it stops short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds genuinely new behavioral context: the prompt is applied additively alongside event-specific prompts, and the call requires recordings:write scope. It does not state that an existing series prompt is overwritten or point to hub_clear_series_custom_prompt for removal, which is a gap given the destructive hint.

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

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

Two tight sentences, front-loaded with the action and scope, followed by the layering rule and the auth requirement. No filler.

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

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

With no output schema and a fully documented parameter schema, the description covers the essential semantics: what changes, at what granularity, and how it interacts with the sibling tool. Missing only the overwrite/clear behavior for an existing series prompt.

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 including the auth/workspace context are documented in the schema. The description adds no parameter-level detail beyond the series-wide semantics, so the baseline 3 applies.

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

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

Specific verb+resource ('Set the custom prompt for an entire recurring series') with explicit scope ('entire recurring series', 'every occurrence'). It clearly differentiates from the sibling hub_set_event_custom_prompt by naming it and describing the layering relationship.

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 semantic context in which this tool applies (series-wide, applied to every occurrence, cumulative with event-level prompts) and names the alternative sibling. It stops short of stating when an agent should prefer series-level over occurrence-level prompting, but the layering explanation makes the distinction inferable.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: API keys are never returned, output varies by auth mode (X-API-Key vs X-Dutify-Accounts), and single-account mode yields a 'default' entry. It stops short of documenting pagination or error behavior, so a 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?

Front-loaded with purpose and return shape, then mode behavior, then the usage trigger. Every sentence adds information; nothing is redundant 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?

There is no output schema, and the description fully compensates by describing the returned entries and field meanings. It also resolves the auth-mode ambiguity that would otherwise block correct interpretation of results. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents both `account` and `workspace` at a high level. The description adds the useful linkage that the returned `name` is the value passed as the `account` argument, but it adds nothing further about the parameters themselves. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the accounts configured for this MCP session') and immediately defines the return shape (one entry per account with `name` and `workspace`). It also distinguishes itself from the workspace-oriented siblings by clarifying what `name` and `workspace` mean, so an agent can tell it apart from list_workspaces/find_my_workspace.

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 'Call this first when you do not know which account names are available', giving a clear trigger condition. It also explains the single-account vs multi-account mode split that determines output. It does not name an alternative tool or state exclusions (e.g. 'not for listing workspaces'), so not 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 establish read-only, idempotent, non-destructive behavior. The description adds useful context beyond annotations by saying only boards the caller can view are returned and by naming the key fields included in each entry.

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 with no wasted wording. The core purpose is front-loaded, followed by the relevant return-value 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 list tool with rich annotations and complete parameter schema descriptions, the description covers purpose, scope, and the important fields returned. It does not mention pagination or exhaustively describe the returned board object, but it is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the account and workspace parameters are fully documented in the schema. The description does not add parameter-specific meaning beyond referring to the current workspace, so the baseline score 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 gives a specific verb and resource: list feature-request boards the caller can view in the current workspace. It is clearly distinguishable from sibling fr_* tools and from list_workspaces/list_spaces by resource, though it does not explicitly name an alternative tool.

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 implies when to use the tool by explaining that the board slug and short-ID prefixes are needed to address requests/bugs in follow-up tool calls. It lacks explicit when-not guidance or named alternatives, 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description does add permission-based scoping ("the caller can view") and confirms page counts are returned, but says nothing about pagination, result limits, or ordering for a list 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 sentences, zero filler: the enumeration scope is front-loaded and the identifier hint follows. Nothing could be removed 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?

There is no output schema, and the description usefully compensates by stating that each entry carries a page count and a `key` field suitable for follow-up calls. Pagination and volume characteristics are the remaining gap for a list tool, but overall it is sufficient to call correctly.

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

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

Schema description coverage is 100%, so both `account` and `workspace` are fully documented in the schema itself (including the ACCOUNT_REQUIRED failure mode). The description mentions "current workspace" only obliquely and adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("List wiki spaces") plus a scope constraint ("the caller can view in the current workspace") and the shape of each item (page count). It implicitly separates itself from wiki_get_space / wiki_get_space_with_pages by being the enumeration call, but never names those siblings explicitly.

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

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

The second sentence gives useful downstream guidance (use `key` as the space identifier in follow-up wiki calls), but that is guidance about using the output, not about when to pick this tool over wiki_get_space or wiki_list_pages. No explicit when-not or prerequisite conditions are stated.

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