Moderation API

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no auth requirements, no indication of what account scope is returned, no note on the (odd) idempotentHint=false. It gives no behavioral context the annotations don't already 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 identical sentences, so the second copy is pure waste rather than reinforcement. Short is good, but duplication with zero additional content fails the 'every sentence earns its place' test.

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 bears responsibility for conveying what a caller gets back, and it says only 'details'. For a read tool with a nested request object and no annotation gaps, this leaves the agent unable to predict the response shape or confirm whether the call is account-wide or project-scoped.

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 reported at 0%, and the description supplies no parameter meaning at all. The nested projectId field does carry a detailed description in the schema, but the wrapping 'request' object is unexplained and the tool description does nothing to clarify how the single parameter affects a single-project account key.

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 text 'Get account details' simply restates the tool name and the annotation title, which is the textbook definition of a tautological description. It names a resource but provides no scope, no distinction from sibling retrieve tools such as projects-retrieve or authors-retrieve, and no detail about what 'account details' actually comprise.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, no exclusions. An agent must infer entirely on its own that this is the entry point for reading account-level information rather than any of the many other retrieve tools in the sibling list.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false; the description adds nothing on top. It does not say what is created, whether duplicates are rejected, whether an organization/project key is needed, or what happens to the queue behaviour fields. No contradiction, but zero added value.

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

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

Two sentences that are literally identical; there is nothing to front-load because no information is present. It is short but only by virtue of being empty, which is under-specification rather than concision.

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 non-idempotent mutation tool with a nested multi-field body, an enum-typed 'type' and 'queueBehaviour', and no output schema. The description covers none of the information needed to construct a valid request or understand the effect of creation.

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

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

The single top-level parameter is a nested 'request' object with a required 'body' containing nine fields (type enum, position, queueBehaviour, possibleValues, filterInQueueIds, etc.), and the schema coverage metric is 0% for the top-level shape. The description does not explain the request/body wrapper, the required fields, or the semantics of any nested field, leaving the agent to reverse-engineer a deep object.

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 is a verbatim restatement of the tool name and annotation title ('Create an action'), which is tautological. It provides no resource detail (what an 'action' is in this moderation/queue system) and does nothing to separate it from siblings such as actions-update, actions-delete, or actions-execute.

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

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

There is no statement of when to use this tool, no prerequisites, and no mention of alternatives. With six other actions-* siblings present, the agent gets no routing signal at all.

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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a crucial behavioral detail beyond annotations: deleting an action also deletes all of its webhooks. It still does not mention permissions, confirmation requirements, or irreversibility, but the cascade detail is significant.

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 brief and front-loaded. The only minor inefficiency is that the first sentence repeats the opening of the second, but the second sentence adds important cascade information without excess prose.

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 delete operation with annotation support and no output schema, the description covers the essential cascade behavior. It could be stronger by stating irreversibility or confirmation expectations, but the destructive hint and schema fill most remaining gaps.

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

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

The description adds no parameter-level meaning; it does not explain the required action ID or the optional projectId. Although the nested schema contains descriptions for those fields, the reported schema description coverage is low, and the description does not compensate by clarifying how to identify the action or scope the request.

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 an action. It also adds the cascade scope (all webhooks), which distinguishes it from actions-update or actions-list. It does not explicitly name sibling alternatives, so it falls short of the top score.

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

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

Usage is implied: use this tool to remove an action, and be aware that its webhooks go with it. There is no explicit when-not guidance, no warning about irreversibility, and no routing advice versus actions-update or webhooks-delete.

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 nothing beyond that: it doesn't explain that authorIds vs contentIds targets differ, that a moderator identity gets recorded, or that casebook cases may be created as a side effect.

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 text is short but redundant: the first line merely repeats the title and the second line repeats the first with a minor scope clause. Brevity here comes from under-specification rather than disciplined editing.

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?

This is a destructive, nested-body mutation with no output schema, yet the description covers none of the operational essentials — target selection semantics, required project scoping, or side effects. For a tool of this complexity the description is materially incomplete.

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

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

The single top-level request object has 0% schema description coverage, and the description offers no compensating detail about actionKey, queueId, duration, or the authorIds/contentIds choice. The nested field descriptions in the schema do some work, but the prose contributes nothing an agent could not already read in the JSON.

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 verb plus resource ("execute a moderation action on one or more content items"), so the basic operation is inferable. But it essentially restates the tool name and title, and never distinguishes this generic action-runner from siblings like content-allow, content-reject, authors-block, or authors-suspend, which do similar moderation 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?

There is no statement of when to use this tool versus the many moderation siblings, no prerequisites (organization key vs project key handling), and no exclusions. The agent is left to guess whether to call actions-execute or a dedicated endpoint such as content-reject.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that results are paginated, which is genuinely useful context beyond annotations, but it omits defaults (page=1, pageSize=20) and whether filtering is supported.

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?

Very short and front-loaded, but the first line 'List moderation actions' is fully redundant with the second sentence, so part of the text does not earn its place.

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

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

For a paginated list tool with a nested object of four undocumented sub-parameters and no output schema, the description should at least explain the queue filter and paging defaults. It says nothing about the returned action objects or result shape.

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

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

Schema description coverage is 0% for the nested request object; only projectId carries a description, while page, pageSize and queueId are entirely undocumented. The description hints at pagination but never names or explains page/pageSize/queueId, so it does little to compensate 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+resource ('List the moderation actions of the project'), which clearly separates it from actions-retrieve, actions-create, actions-delete and the other action siblings. It does not, however, differentiate itself from the many other list tools (queue-items-list, authors-list) or say what a moderation action contains.

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

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

No guidance on when to choose this over actions-retrieve (single action lookup) or how to narrow results by queue. The only usage-adjacent statement is 'The list is paginated', which is a behavior note rather than selection guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds nothing beyond that: no mention of not-found behavior, project-key scoping effects, or what is returned. It does not contradict annotations, but it contributes no behavioral context.

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?

Short, but it wastes half its length on a verbatim repeat of the first sentence. Brevity here reflects under-specification rather than disciplined editing; there is no front-loaded scope or precondition.

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 nested-object retrieval tool with no output schema, the description should explain what an action is and what comes back. Instead it supplies only the resource noun, leaving the agent to infer everything from the parameter schema.

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

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

Schema description coverage is reported as 0%, and the description says nothing about either the id or projectId field. The description does not compensate for the low coverage, leaving project-key scoping semantics to the schema alone. One required nested parameter with zero narrative support.

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 two sentences restate the tool name: 'Get an action' then 'Get an action by ID.' The only added information is 'by ID,' which implicitly distinguishes it from actions-list, but nothing about scope, return content, or difference from actions-update/actions-execute is given.

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

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

No when-to-use guidance and no mention of alternatives, despite seven sibling actions-* tools including actions-list. The agent must infer that this is the singular fetch and must guess whether projectId is required.

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

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

Annotations already flag destructiveHint=true, non-idempotent, non-readOnly, so the safety profile is covered structurally and nothing here contradicts it. But the description adds zero context beyond the annotations: it does not say which fields are overwritten, whether omitted fields are preserved, or what permissions are needed — notable gaps for a destructive update.

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

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

It is short, but the single sentence is literally duplicated, which is pure waste rather than conciseness. The problem is under-specification, not verbosity.

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

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

For a destructive mutation with a nested body of ten fields and no output schema, the description says nothing an agent needs in order to call it correctly — not the id requirement, not partial-vs-full update semantics, not the effect of queueBehaviour.

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?

Top-level schema description coverage is 0% — the single `request` wrapper param is undocumented — so the description would need to compensate, and it does not. The nested body properties (name, type, position, queueBehaviour, possibleValues) do carry their own inline descriptions, which keeps this above a 1, but the description contributes nothing about the update semantics of those 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 is 'Update an action' repeated twice, which is a pure restatement of the tool name and annotation title. It gives no verb-plus-resource specificity and does nothing to distinguish this from actions-create, actions-delete, or actions-retrieve.

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

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

There is no guidance on when to use this tool versus the many sibling action tools. An agent must infer entirely from the name that this is the PATCH-style mutation for an existing action.

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

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

With readOnlyHint=true and destructiveHint=false, safety is already covered, so the description adds value by specifying the aggregation over a time window and descending ordering. However, it says nothing about result contents, pagination, default limit behavior, or the project-auth requirement, which is significant for a ranked analytics endpoint.

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 remain short, but the first line is essentially repeated by the second, so the description wastes half its length restating the same purpose. The ordering rule is front-loaded reasonably well.

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 analytics query with no output schema and a nested parameter object, the definition is minimally adequate: it conveys the metric, time window, and ordering, but omits the returned shape and how limit/channel/projectId affect output.

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

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

The nested request object contains limit, range, channel, and projectId; the schema itself documents range and projectId, but the description only gestures at 'time window' and 'largest first'. It adds no meaning for the limit default of 6, the channel filter, or how projectId scopes results, leaving the description roughly at 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 gives a specific verb and resource ('Get the authors with the most flagged content') plus a ranking rule ('largest first'), which is enough to distinguish it from sibling analytics tools like analytics-summary or analytics-channels. It does not explicitly name those siblings, but the flagged-content metric is distinctive.

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

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

There is no guidance on when to use this versus authors-list or the other analytics-* tools, and no stated exclusions or prerequisites. Only an implied 'time window' context is provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description contributes the semantic scope of the result (rules/casebook/human review split), but says nothing about permissions, project/organization key requirements, or bucket granularity, which the schema carries instead.

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

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

Two short sentences, front-loaded with the identifier and then the payload contents. No filler, though the heading sentence merely restates the title rather than adding 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, so the description does its job of explaining what the returned breakdown represents. For a single nested request object with read-only annotations, that is nearly sufficient; the remaining gap is the undocumented 'channel' 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?

Reported schema coverage is low, so the description should compensate, yet it only obliquely gestures at the time window and says nothing about the 'channel' filter or the project scoping rules. The range and projectId semantics live entirely in the schema text; 'channel' is undocumented in both places.

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

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

The description names a specific verb+resource ('Get the automation breakdown') and enumerates what the breakdown contains: settled by rules or casebook, sent to human review, and reviewer decisions. That is clearly distinguishable from analytics-summary/analytics-policies/analytics-authors, though those siblings are never named, which keeps it just under 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?

Usage is implied by the domain it describes (analytics over automated handling) rather than stated. There is no explicit 'use this when...', no exclusion against analytics-summary or queue-get-stats, and no mention that this is read-only reporting rather than a resolution action.

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

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

Annotations already declare readOnly=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds the metric set and the time-window scoping, but does not mention bucket granularity (hourly vs. daily), whether empty channels are omitted, or the odd idempotentHint=false.

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

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

Two short lines, front-loaded with the verb+resource and immediately followed by the metric list; no filler. The title line largely restates the first sentence, which is the only redundancy.

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

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

With no output schema, the description usefully names the metrics returned and the per-channel grouping plus the time-window dimension. It stops short of describing entry shape or channel identity fields, but is adequate for a simple read-only analytics endpoint.

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?

Reported coverage is 0% for the single top-level 'request' parameter, so strictly the description would need to compensate; instead the nested schema (range enum semantics, projectId key rules) carries that load. The description only echoes 'time window', adding no detail beyond the schema.

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

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

States a specific verb and resource ('Get analytics per channel') and enumerates the metrics returned (requests, flags, flag rate). 'Per channel' distinguishes it from analytics-authors and analytics-summary, 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?

The purpose implies the usage (per-channel breakdown over a time window), but there is no explicit when-to-use, when-not-to-use, or which sibling analytics-* tool to pick for a different dimension. An agent must infer the routing from the name alone.

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

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

Annotations already cover read-only, non-destructive, closed-world behavior, so the description's main added value is behavioral: results are ordered largest first and include a count from the preceding window. It does not explain pagination, filtering behavior, or auth/project scoping beyond what the schema minimally states.

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

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

It is short and front-loaded: the first sentence states the core action, and the second clarifies ranking and count. The phrasing 'with the count in the window before' is slightly awkward, but there is little wasted text.

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

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

For a nested-parameter analytics query with no output schema, the description is incomplete. It says what is ranked and ordered, but omits filter semantics, limit behavior, auth/project scoping, and enough return-value detail for an agent to call it confidently.

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

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

The description mentions a time window, which maps loosely to the range parameter, but it does not explain limit, channel, or projectId semantics. With schema description coverage reported as 0%, the description does not compensate for the nested request object's undocumented parameters.

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

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

The description states a specific verb and resource: getting policy labels that flagged the most content. It also specifies ordering (largest first) and count context, which distinguishes it from analytics siblings like analytics-authors, analytics-channels, and analytics-volumes.

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

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

The description implies this is the analytics tool for flagged policies, but it gives no explicit when-to-use guidance, no exclusions, and no comparison to sibling analytics tools. An agent must infer selection from the resource name alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context beyond that: results come with the prior window for trend comparison, plus review-queue backlog and an optional flag-rate spike. It stops there – nothing about permissions, what happens with a project key vs organization key, or behavior of the default window vs explicit values.

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 first line merely restates the title, but the two following sentences are dense and front-load the important information (what the totals are, then the trend and extras). No filler beyond the redundant opening line.

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 a decent job describing the returned shape (totals, trend, backlog, spike). However it leaves the nested `request` object and the `channel` parameter wholly unexplained, and gives no hint about the default 30-day window or how project scoping errors surface, so an agent could call it with an invalid channel or wrapper without warning.

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 reported at 0%, and the description mentions no parameter at all – not the nested `request` wrapper, not `channel` (which has no description anywhere), and not the range/channel/projectId options. The schema itself does describe `range` and `projectId`, so the agent is not fully blind, but for a nested-object parameter the description should at minimum explain the wrapper and the undocumented `channel` field.

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

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

The description names the resource (project analytics summary) and enumerates the specific metrics returned: requests, flags, flag rate, allowed, rejected, sent to review, plus backlog and spike detection. That tells an agent this is the aggregate/totals view, implicitly distinct from the breakdown siblings (analytics-authors, analytics-channels, analytics-policies). It never names a sibling explicitly, so it stops short of a 5.

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

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

Usage is only implied by the content list – an agent can infer this is the high-level totals tool versus the per-dimension analytics tools, but there is no explicit 'use this when you want X, use analytics-policies when you want Y' guidance and no preconditions stated. No alternatives are named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that — hourly vs daily bucketing tied to each range and ascending (oldest first) ordering — but says nothing about return shape, whether zero-volume buckets are included, or scoping by channel/project.

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

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

Two short sentences, front-loaded with the resource and immediately followed by the concrete dimensions and granularity. No filler. Minor duplication between the leading line and the tool name/title, but nothing wasteful.

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

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

For a simple read-only analytics endpoint with one nested object this is adequate, but with no output schema the description is the only place return values could be described and it omits them entirely (field names, bucket shape, whether empty periods appear). Combined with the undocumented 'channel' filter, there are real gaps an agent must guess at.

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 restates the range enum semantics (24h hourly, 7d/30d/90d daily) which is already spelled out in the schema's range description, so it adds little there. The top-level 'request' wrapper and the 'channel' parameter are undocumented in both schema and description; only projectId is well covered, and only by 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 concrete verb and resource ('Get volumes over time') and enumerates the exact measures returned: requests, flags, rejections and reviews, with bucket granularity. That makes the time-series nature clear against a crowded analytics family, though it never names analytics-summary or analytics-channels to draw the boundary explicitly.

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

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

There is no explicit 'use this when…' guidance and no mention of when to prefer analytics-summary, analytics-channels, analytics-authors or analytics-policies instead. The only usage signal is implicit in the metric list and the 'oldest first' ordering 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 and idempotentHint=false, so the safety profile is covered. The description adds real substance beyond that: what blocking actually does ('cannot post new content') and that it is reversible ('until unblocked'). It does not explain what happens on repeat invocation despite idempotentHint=false, 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?

Short and front-loaded, with the effect stated immediately. The leading 'Block author' line restates the title and the second sentence re-states the verb, so there is minor redundancy, but nothing is padded.

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

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

For a destructive, nested-body mutation tool, the description omits relevant context: that 'reason' is persisted and emitted in a webhook, and the projectId scoping rule (organization keys must name a project). Annotations cover the destructiveness, but the operational caveats are left to 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?

The description says nothing about parameters, and the aggregated schema coverage is reported as 0% at the top level — the 'request' wrapper is undocumented. However, the nested properties (id, body.reason, projectId) do carry schema descriptions, so param meaning is recoverable from the schema itself; the description simply adds no value here.

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

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

The description gives a specific verb and resource ('Block an author') and states the concrete effect ('A blocked author cannot post new content'). It does not distinguish this from the sibling tool authors-suspend, which is the obvious ambiguity an agent would face, so it stops short of a 5.

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

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

There is no guidance on when to block versus suspend (a direct sibling), and no stated prerequisites such as required project scoping or API-key permissions. The only implicit routing signal is the phrase 'until unblocked', which hints at the reverse operation but does not tell the agent when to choose this tool.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds real behavioral value by explaining the auto-creation lifecycle. However, it omits the behavior most likely to bite an agent: what happens if an author with that external_id already exists — error, upsert, or duplicate? Retry semantics matter for a non-idempotent create.

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 opening line 'Create a new author' is immediately repeated verbatim in the second sentence, so roughly half the text is redundant. The valuable lifecycle warning does land early enough to be read, but the duplication wastes the most prominent position in the description.

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 create operation taking a nested body with twelve optional/required fields and no output schema, the description should say what is returned (the new author ID?), what happens on duplicate external_id, and why metadata matters for moderation. Only the auto-creation caveat is covered, so an agent must guess at the failure modes and the response shape of a non-idempotent write.

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 reported at 0% and the description contributes nothing about parameters — not the mandatory external_id, not the projectId scoping rules, not the metadata object that feeds moderation. The nested property descriptions in the raw schema do document individual fields, but the definition itself carries none of that weight, leaving an agent to infer that external_id is the identity key for duplicate handling.

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 author') that is unmistakable against siblings like authors-update or authors-list. It also clarifies the resource relationship — authors normally come into existence via moderation — which sharpens the mental model. It stops short of naming a sibling to defer to, but the operation itself is unambiguous.

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

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

The sentence 'Typically not needed as authors are created automatically when content is moderated' is a genuine when-not-to-use signal plus an implied alternative path (content-submit). What's missing is a positive case ('use when you need to pre-register an author with a known external_id before any content exists') and any pointer to authors-update for existing records.

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, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description goes meaningfully beyond that by enumerating exactly what is wiped (status, blocks, trust level, metrics, action history) and by explaining that the author is recreated with a clean record on the next moderation — a non-obvious consequence that materially affects the decision to call 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?

Short and front-loaded, with the key destructive consequence in the second sentence. The opening line "Delete an author" merely restates the title and name before "Delete a specific author" repeats it again, a small redundancy.

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

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

For a single-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies the consequence model an agent needs. Only the absence of alternative-routing guidance and permission requirements keeps it from being complete.

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

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

The description says nothing about the id or projectId arguments. The reported coverage of 0% is pessimistic — the nested schema fields do carry useful text (external vs moderation-assigned ID, project scoping rules) — so the schema largely carries the load, but the description adds no filtering or identity semantics of its own.

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

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

States a specific verb and resource ("Delete a specific author"), which is inherently distinguishable from the mutation siblings authors-block, authors-suspend, and authors-update. It never names those siblings explicitly to route the agent, but the verb does the differentiating 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?

There is no guidance on when to choose deletion over the softer authors-block or authors-suspend, nor any stated prerequisites or permissions. The agent must infer the escalation path from sibling names alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds two genuinely useful traits beyond that — the result set is paginated, and the default order is most-recently-active first — but says nothing about page-size limits, total counts, or whether filters affect ordering.

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

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

Two short sentences plus a heading line, with the behavioral detail (pagination, default ordering) front-loaded and no filler. The leading "List authors" line is redundant with the title and annotations, a minor waste.

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

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

For a read-only list tool with no output schema, the description gives the essential shape but leaves an agent unable to use the filtering and sorting parameters correctly, and gives no sense of the returned record structure beyond three named fields. Adequate to call, incomplete to call well.

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 effectively 0% for seven nested sub-parameters, so the description must carry the load and largely does not. "The list is paginated" loosely implies page/pageSize, and "active most recently come first" implies the lastActive default, but sortBy's seven enum values, lastActiveDate, and memberSinceDate get no explanation anywhere.

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 authors of the project") and enumerates the fields returned (status, trust level, content metrics), which lets an agent separate it from write siblings like authors-update or authors-block. It does not, however, distinguish itself from the analytics-authors sibling, which plausibly overlaps.

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 verb; there is no explicit "use this when..." statement, no exclusions, and no mention of when analytics-authors should be preferred. The default-ordering note gives a hint about intended behavior but is not routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds that results include 'historical data and analysis,' which hints at payload depth, but says nothing about behavior on unknown IDs, permission requirements, or the shape/size of the response — and idempotentHint=false on a read tool goes unremarked.

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

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

Two short sentences, front-loaded with the core action; nothing extraneous. The second sentence is largely an elaboration of the first and repeats the title, a minor redundancy rather than a 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?

For a single-parameter read tool with annotations and no output schema, the definition covers the essential purpose. Gaps remain: the description does not explain what 'historical data and analysis' concretely contains, nor the project-scoping rule that the nested schema imposes, leaving the agent dependent on schema prose alone.

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

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

Schema description coverage is reported as 0% at the top level, and the description never mentions the id or projectId parameters. However, the nested schema itself carries substantive prose for both fields (external vs. moderation-assigned ID, project scoping rules), so the parameter burden is largely carried by structured data rather than the description.

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

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

States a specific verb and resource ('Get author details' / 'detailed information about a specific author'), making single-record retrieval unambiguous. It does not explicitly distinguish itself from authors-list or analytics-authors, so the agent must infer the singular-vs-list split from the word 'specific'.

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

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

Usage is only implied: an agent can infer this is the tool for fetching one author once it already has an ID, versus authors-list for enumeration. There is no explicit when-to-use, when-not-to-use, or named alternative, and the choice between authors-retrieve and analytics-authors for author-level stats is left unaddressed.

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 risk is known. The description adds nothing beyond that: no mention of reversibility (authors-unblock exists), no permission/API-key requirements, no webhook side effect, and 'built-in suspend action' is filler.

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

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

Two short sentences that are front-loaded, but the second sentence largely restates the first ('Suspend author' / 'Block an author') with no added information. There is no waste of length, but also little payload.

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, non-idempotent mutation with a nested request object, no output schema, and 0% schema description coverage, the description needs to explain the block-vs-suspend difference, duration semantics, and how to reverse it. None of that is present.

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

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

Schema description coverage is reported as 0% and the description mentions none of the nested parameters (id, reason, duration, projectId). It never connects 'limited time' to the duration field or its 24-hour default, so the description does not compensate for the schema 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+resource ('Suspend author', 'Block an author') and adds the scope qualifier 'for a limited time'. That qualifier hints at a distinction from the siblings authors-block/authors-unblock, though the description never names them.

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

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

Usage is only implied: 'limited time' suggests choosing this over a permanent block, but no alternative tool is named and no condition for when-not-to-use is given. An agent must infer the block-vs-suspend split from sibling names alone.

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

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

Annotations already disclose that this is a non-readonly, non-destructive mutation. The description adds the outcome ('so they can post new content again'), but omits auth requirements, webhook/audit side effects, and why idempotency is false. Given annotations cover the safety profile, this is adequate but thin.

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

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

Two short sentences, front-loaded with the action and immediately followed by the effect. No wasted words; the first line duplicates the title but serves as a clear lead-in.

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 mutation with one nested request parameter, the description covers the core outcome but omits permission/project-context nuances (projectId requirement with org keys) and the audit/webhook role of the reason field. These are present in the schema, but the description does not tie them together for the 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 description coverage is reported as 0% for the top-level request object, and the description adds no parameter meaning at all. It does not mention the required author id, optional reason, or project scoping, so it fails to compensate 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 ('Unblock author') and explains it applies to a 'blocked or suspended author'. This clearly distinguishes it from the sibling authors-block and authors-suspend tools, which perform the inverse operation.

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 condition for use is explicit: unblock a blocked or suspended author so they can post again. However, it does not name alternatives (e.g., authors-block, authors-suspend) or state when not to use it, leaving routing to inference.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, so the description needs only to add surrounding context — but it adds none. Critically, it never says whether the 'body' fields are replaced wholesale or merged as a partial update, which is the single most important behavioral fact for a destructive non-idempotent mutation; nor does it mention permissions or whether omitted fields are cleared.

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?

Both sentences express the identical proposition, so the second earns nothing. Brevity here is a product of under-specification rather than efficient front-loading.

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?

This is a destructive, non-idempotent mutation on a nested-object schema with no output schema and no annotations beyond hints. The description omits update semantics, required permissions, the ID-type ambiguity, and project scoping — all of which an agent needs 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 reported as 0%, so the description must carry the load and it does not: it never explains the dual ID semantics (external ID vs moderation API ID), the projectId scoping rules, or the optional author body fields. The nested schema happens to document individual fields, but the description's role in disambiguating the envelope parameters is unfilled.

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 two sentences restate the tool name ('Update author details' / 'Update the details of a specific author') without adding a specific verb-resource scope. It never distinguishes itself from the many sibling author tools (authors-block, authors-suspend, authors-delete, authors-create), so an agent learns nothing about what 'details' means or how this differs.

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

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

There is no guidance on when to use this versus alternatives such as authors-create for new authors or authors-block/authors-suspend for status changes. The agent must infer from the name alone that this is the general-purpose edit path.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write. The description adds genuinely new behavioral facts: channels are created with default rules, the project's first channel becomes its default, and the call requires the channels:write permission. That is substantive context beyond 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?

Short and mostly front-loaded, with the key constraints in one sentence. The leading line duplicates the title and the 'Create a channel in a project' clause, wasting roughly a fifth of the text.

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

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

For a create tool with no output schema, the description covers the essentials an agent needs before calling: permission requirement, default-rule behavior, and the first-channel-becomes-default side effect. It omits the uniqueness constraint on key and what the response returns, but neither is blocking.

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 names no parameters and adds nothing about the request body or projectId. The schema's nested properties (key, contentType, description) do carry descriptions, so the effective documentation gap is smaller than the reported 0% coverage suggests, but the description itself contributes zero 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?

States a specific verb and resource ("Create a channel") plus the placement scope ("in a project"), which distinguishes it from siblings like channels-update or channels-duplicate. The first line merely repeats the title, but the second sentence carries the real purpose.

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 ("channels:write") and project scoping imply when the tool is applicable, but no alternative is named and no exclusion is given — an agent could reasonably confuse this with channels-duplicate, which also produces a channel.

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 destructiveHint=true annotation: it discloses that the key is freed for reuse, that the oldest remaining channel is promoted when the default is removed, that Slack moderation must be cleared first, and that channels:write is required. These are exactly the side effects and auth requirements an agent needs before an irreversible 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?

Dense and front-loaded: consequences, default-promotion behavior, prerequisite, and permission in four tight sentences. The opening repeats the title and then restates "Delete a channel" as the first sentence, which is a small 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?

With no output schema and annotations already covering the read-only/destructive profile, the description supplies the missing pieces — side effects, prerequisite, and permission scope — so nothing an agent needs before invoking a destructive delete 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?

The single nested `request.id` parameter is not mentioned in the description at all; the schema itself carries only a bare "The ID of the channel." label. Since there is only one parameter and the schema names it adequately, this is a minor gap, but the description adds no meaning about identifier source or format.

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

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

States a specific verb and resource ("Delete a channel") that is unmistakable against siblings like channels-update, channels-duplicate, and channels-retrieve. The follow-on sentences reinforce the scope by describing the exact consequences of deletion rather than restating the name.

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 precondition — a channel still moderating a Slack workspace must be disconnected first — which tells the agent when the call will fail. It does not explicitly route to alternatives, but for a destructive terminal operation the sibling set (update vs duplicate vs delete) makes the choice obvious.

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=false, destructive=false, idempotent=false, openWorld=false). The description adds real context on top: the exact scope of what is replicated, the Discord/Slack/WordPress exclusion, and the required `channels:write` permission. It could still say whether the original is untouched and what the new channel's initial state is.

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 verb and immediate effect, then scope, then permissions. Only mild redundancy between the title echo and the opening line.

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

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

For a one-parameter, no-output-schema copy operation, the essentials are present: what is copied, what is deliberately not copied, and the permission required. Return shape and how the copy is identified are left implicit, but not blocking.

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?

Context signals report 0% schema description coverage at the parameter level, and the description contributes nothing about `request`, `id`, `name`, or `key` — notably not the timestamp/'copy' defaulting behavior. The nested schema does document those fields, so the gap is narrow but the description does not compensate for the low coverage signal as required.

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

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

States a specific verb (duplicate/copy) and resource (channel), and immediately defines the copy semantics: 'in its project, with every setting, policy, rule and wordlist'. That is enough to separate it from channels-create and channels-update 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 description implies usage (copy rather than build from scratch) and gives one useful exclusion — integrations are not copied — which the agent needs before choosing this over channels-create. But it never names channels-create or states when NOT to duplicate, so routing is left partly to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the auth requirement (`channels:read`), which is real value beyond structured fields, but says nothing about ordering, result size, or what a page contains.

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 the core action front-loaded and the permission requirement last. The opening 'List channels' largely repeats the title, which is mild waste, but nothing else is padded.

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

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

For a simple paginated read tool with annotations covering safety, the essentials are present: scope, pagination, and auth. Missing only the return shape, which matters a bit more since there is no output schema, but the gaps are minor.

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

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

Schema coverage is essentially 0% for the pagination fields (page, pageSize have no descriptions), but the description does flag that 'the list is paginated', which points the agent at those nested fields. It adds no detail on defaults, max page size, or projectId format beyond what the schema shows.

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 channels') plus the scope ('in a project'), which clearly separates it from channels-retrieve, channels-create, and analytics-channels among the siblings. An agent can pick this out without opening the schema.

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

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

It states the required permission scope (`channels:read`), which is useful context, and 'in a project' implies project-scoped listing. But it never says when to use this versus channels-retrieve or analytics-channels, and offers no exclusions or caveats.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new context — the required `channels:read` scope — but says nothing about return shape or behavior when the ID does not exist.

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?

Very short and front-loaded, with the permission requirement placed after the core action. The opening line duplicates the annotations title, so a sentence of the text is redundant rather than earning its place.

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

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

For a simple read-only single-record lookup this is close to adequate, and annotations plus the input schema cover most of what an agent needs. With no output schema, though, the description could say what a channel object is or what happens on a missing ID, and it leaves the nested request envelope unexplained.

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 effectively 0% at the parameter level (only the inner `id` field carries a terse description), and the nested `request` wrapper is undocumented anywhere. The description's "by ID" confirms the parameter's meaning but adds no format, source, or constraint detail.

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 channel") and narrows scope with "by ID," which implicitly separates it from channels-list and channels-update. It never names a sibling explicitly, so 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?

"by ID" implies this is the single-record retrieval path versus channels-list, and the `channels:read` permission note gives a prerequisite. There is no explicit when-to-use/when-not guidance or mention of alternatives such as channels-list for enumeration.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false; the description adds two things annotations cannot convey: PATCH-style merge semantics (omitted fields persist) and the required `channels:write` scope. It does not expand on the destructive surface (e.g. that mutating `key` breaks integrations), which the schema carries instead.

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 immediately followed by the merge rule and the permission requirement. The only inefficiency is the redundant restatement of 'Update a channel' in the title line and the first sentence.

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

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

For a destructive, non-idempotent mutation over a nested object with ~18 settable fields and no output schema, the description covers the permission gate and partial-update behavior but says nothing about what the call returns, whether nulling fields is possible, or the risk that changing certain fields breaks downstream integrations. Adequate, not 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?

Top-level schema description coverage is reported as 0% for the single `request` parameter, so the description is expected to compensate. It only partially does: the merge semantics explain how the nested `body` behaves, but nothing describes the request envelope or which field groups exist. Individual body properties are documented inside the schema itself.

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

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

States a specific verb and resource ('Update a channel'), which cleanly separates it from siblings like channels-create, channels-delete, channels-retrieve, and channels-duplicate. It stops short of explicitly naming any sibling or noting what makes update distinct beyond the verb.

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

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

'Fields you leave out keep their value' is a genuine usage rule that tells the agent to send partial bodies rather than a full object, and the permission line signals a precondition. But there is no guidance on when to use this versus channels-create/channels-duplicate, nor any exclusion or ordering advice.

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

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

Annotations already declare it is a non-read-only, non-destructive, non-idempotent mutation, so the safety bar is lower. The description adds one genuinely useful behavioral fact beyond annotations: the item is resolved in the review queue as a side effect. It does not disclose what happens on a repeat call against an already-resolved item, nor the permission model.

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?

Very short, but the first line 'Allow content' merely restates the title and name before the real content arrives. The substantive sentence is front-loaded reasonably, but the redundancy costs 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?

A mutation tool with a deeply nested request object, no output schema, and no annotations about side effects beyond the flags. The description omits return shape, error conditions, and what 'resolve in the review queue' means operationally for a multi-queue project.

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?

Top-level schema description coverage is reported at 0% and the single `request` parameter is opaque, so the description is expected to compensate but says nothing about id, moderator, queueId, or createCasebookCase. The nested schema properties do carry their own descriptions, which prevents this from scoring 1.

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 (allow) and resource (a content item), and adds that the item is resolved in the review queue. Against siblings content-reject and content-submit the operation is clearly distinguishable, though the description never explicitly contrasts itself with reject.

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

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

No statement of when to allow versus reject, no prerequisites (moderator identity, project key scoping), and no guidance on the queue-resolution consequence. Usage is only implied by the tool name and the mention of the review queue.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known. The description does add one non-obvious trait beyond the annotations: the action also resolves the corresponding review-queue item. It omits whether the action triggers a webhook event, whether it can be undone, and what happens if the item is already resolved.

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

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

Two short sentences, front-loaded with the action, no filler. The first line merely echoes the title and tool name, which is mild redundancy but harmless.

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 it does and one side effect (queue resolution) but not the return shape, failure modes, or whether a webhook fires. Adequate to call it, not enough to call it confidently in edge cases.

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 contributes no parameter meaning at all. However, the input schema itself carries per-field descriptions for id, reason, queueId, moderator, createCasebookCase and projectId, so the agent is not left blind — the baseline of 3 applies since 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+resource ('Reject a content item') and adds a concrete effect: it uses the built-in reject action and resolves the item in the review queue. It does not distinguish itself from the obvious counter-tool content-allow or from queue-items-resolve, which handle adjacent decisions.

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

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

No guidance on when to reject versus allow, versus resolving a queue item directly, or what prerequisites (project key, moderator identity) are needed. The agent must infer the whole decision context from the sibling list.

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

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

Annotations declare a non-idempotent, non-destructive write, so mutation is at least signaled structurally. The description adds nothing beyond that: it doesn't mention that submission triggers policy analysis, creates a review-queue item, populates analytics/author history, or any side effects around doNotStore.

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 words is not conciseness but under-specification; there is no structure, no front-loaded purpose, and nothing that earns or justifies the omission.

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 deeply nested moderation-submission tool with 30+ policy variants, a clientAction recommendation system, and no output schema, a two-word description is completely inadequate; an agent cannot confidently call this correctly from the description alone.

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

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

The single top-level `request` parameter has zero description coverage and the description says nothing about its structure, the required body/content shape, project scoping, or the policy override option. The nested schema fields do carry descriptions, but the composite request envelope – the main thing an agent must construct – is undocumented and unmitigated by the 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?

"Submit content" restates the tool name with no added specificity – it never says the content is sent for moderation, that a moderation result/review-queue item is produced, or how it differs from siblings like content-allow and content-reject.

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

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

No when-to-use, when-not-to-use, or alternative guidance of any kind. An agent has no way to know whether to call this versus content-allow/content-reject or the queue tools.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write; the description adds genuinely new behavioral context: the request is human-read by the team, can be answered by email, and is throttled at 5 requests per minute per organization. It does not explain what happens when the rate limit is exceeded or what identifier/response the call yields, but the rate-limit and follow-up-reply details are real value beyond the annotation set.

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

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

Two sentences, front-loaded with the primary action, followed immediately by the recipient and rate limit. Nothing is redundant and the operational constraint (5/min per org) is easy to locate.

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

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

For a one-parameter but deeply nested object with no output schema, the description covers purpose, audience, follow-up behavior and rate limits well, which is sufficient for an agent to decide to use it. It falls short on the request payload shape: an agent must open the nested schema itself to learn that `body.title` and `body.description` are required, and there is no note about what the call 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?

The single required parameter `request` is a nested object with zero top-level schema description coverage; the description never mentions the request envelope, the mandatory `title`/`description` body, the `type` enum, or the `projectId` field. One could argue the nested properties carry their own descriptions, but the description itself contributes nothing to help an agent assemble a valid request, and it does not explain that projectId is optional or which fields are required.

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

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

States a specific verb (send) and resource (feedback) and names the concrete payload types: feature request, bug report, or other feedback directed at the Moderation API team. The purpose is unambiguous and no sibling tool in the list covers feedback submission, so it is clearly distinct even without an explicit sibling callout.

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

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

Usage is implied by the phrasing 'Sends a feature request, bug report or other feedback' – an agent can infer this is the tool for reporting issues or requesting features rather than a data-operation tool. However, there is no explicit when-to-use/when-not-to-use guidance and no named alternative (e.g., what an agent should do instead if it merely wants to file a support ticket vs. a bug).

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

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

Beyond the annotations, it discloses that the secret key is returned by the call, existing project keys are unaffected, and the caller needs `projects:write` permission. This is useful behavioral context for a non-idempotent create operation and does not contradict the annotations.

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

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

The description is short and front-loaded, with useful rationale for separate keys and the permission requirement. The opening line slightly repeats the title, but the remaining sentences earn their place.

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

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

For a create-secret-key operation with no output schema, the description covers the key behaviors an agent needs: it returns the secret, requires project write permission, and does not invalidate existing keys. It could say more about the returned key's one-time visibility or format, but the essential context is present.

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

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

The description implies project selection ('for a project') and per-app/per-computer naming, but it does not explicitly explain the `request.id` or `request.body.name` fields. The nested schema does document both fields, but the top-level `request` wrapper has no description and the stated schema coverage is low, leaving some 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?

The first sentence states a specific verb and resource: create a project API key. It also distinguishes the output as a secret API key returned by the call, so an agent can confidently tell this apart from project CRUD or other create 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 clear usage context: use one key per app or computer so keys can be revoked independently, and notes that existing keys keep working. It does not explicitly name alternatives or when not to use this tool, but the intended scenario 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 declare readOnlyHint=false, destructiveHint=false and non-idempotency, and the description adds meaningful context beyond them: it discloses the side effects (channel, review queue inbox, secret API key are provisioned) and the authorization requirements ('projects:write' plus a key that reaches all projects). It stops short of describing what happens on duplicate names or how the API key is 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?

It is short and front-loaded, with the creation summary and permission requirement in the first two sentences. The opening line largely restates the tool name/title before the more informative sentence, a small redundancy that keeps it from a 5.

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

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

For a creation tool with no output schema and a nested object parameter, the description covers side effects and auth well but never says what is returned — notably whether the newly minted secret API key is included in the response, which an agent needs to know since it is shown only once. That makes it adequate but incomplete.

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 computed schema coverage is 0% at the top level, but the nested request properties do carry their own descriptions, so much of the parameter semantics is already documented in the schema. The description adds real value by explaining the domain/context interplay — supplying either makes the project suggest platform policies — but says nothing about name, brief, or usedByMinors.

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

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

The description states a specific verb and resource ('Create a project') and goes further to enumerate the artifacts created (a channel, a review queue inbox, a secret API key), which distinguishes the outcome from siblings like projects-duplicate or projects-update. It does not explicitly name a sibling alternative, keeping it below a 5.

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

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

It gives a conditional usage cue ('Give a domain or context and the project suggests policies for the platform') and states the required permission, which implies when the tool is appropriate. However, there is no explicit guidance on when to use this versus projects-duplicate or projects-update, and no exclusions or preconditions beyond the permission 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?

The description adds substantial detail beyond the annotations: it names what is destroyed (channels, queues, API keys, stored content), states irreversibility, notes immediate API key invalidation, and specifies the required `projects:write` permission.

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

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

The description is well structured and front-loaded: purpose, scope of deletion, irreversibility, API key impact, then permission. The opening phrase repeats the tool name, which is a minor redundancy but does not hurt comprehension.

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

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

For a simple destructive deletion tool with no output schema, the description covers the critical behavioral consequences and permission requirement. The main remaining gap is the lack of explicit parameter guidance for the nested project ID.

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 only one required nested `request.id` parameter and reported schema description coverage at 0%, the description does not explain the project ID argument or the nested request shape. It relies on the resource name alone to imply 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?

The description starts with a specific verb and resource: 'Delete a project.' It clearly distinguishes this destructive operation from siblings like projects-update, projects-duplicate, and projects-create.

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 clear context for when this operation applies and emphasizes that it cannot be undone. It does not explicitly compare against alternatives such as projects-update, but the destructive purpose is unambiguous.

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

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

Annotations only say this is a non-readonly, non-destructive, non-idempotent write. The description goes well beyond that by disclosing the non-obvious side effects an agent must plan around: the copy receives its own secret API key, and webhooks, integrations, API keys and content are NOT carried over (implying follow-up calls). It also flags a cross-project auth requirement.

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 is front-loaded in the first clause, followed by the payload inventory, the exclusions, and finally the permission prerequisite. Every sentence carries information an agent needs; there is no restatement of the tool name or filler.

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

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

For a mutation tool with no output schema, it covers scope, side effects, and auth well. The remaining gap is the return value: it doesn't say whether the new project object or just an ID comes back, nor what happens if the source project ID is invalid. Minor, but it is exactly the kind of thing a no-output-schema tool should state.

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 reported as 0% for a single nested `request` object containing `id` and `body.name`. The description implies a source project must be identified but adds nothing about the `name` parameter or the '(copy)' default behavior, leaving the schema's own inline text to carry the parameter burden. Baseline 3 for effectively undocumented-in-description parameters.

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

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

States a specific verb and resource ('Duplicate a project') and then enumerates exactly what the copy includes (settings, channels, policies, rules, wordlists, moderation actions, review queues) and what it excludes (webhooks, integrations, API keys, content). That inclusion/exclusion split is what separates this from projects-create and the various *-create siblings without the agent needing to open another 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 establishes the condition for use (copying an existing configuration into a new project) and states the prerequisite: the `projects:write` permission plus a key that reaches all projects. It doesn't explicitly name projects-create or channels-duplicate as the alternative for 'build from scratch' or 'copy one channel', so the routing is implied rather than spelled out.

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

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

The annotations already declare this as a non-destructive, read-only operation, and the description adds useful context by stating the required `projects:read` permission and that results are paginated. It stops short of explaining pagination behavior or response format, but it provides meaningful operational 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?

The description is short and front-loads the main action before adding pagination and permission details. The initial 'List projects' line slightly duplicates the following sentence, but overall there is little wasted text.

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

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

For a simple read-only list tool with annotations covering safety, the description gives the essential context: organization scope, pagination, and permission requirements. However, with no output schema and no explanation of the returned project representation or pagination mechanics, it is only minimally sufficient for an agent to invoke and interpret the tool confidently.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only says the list is paginated, which hints at the nested `page` and `pageSize` fields but does not explain their defaults, constraints, or usage, leaving most parameter semantics to inference from property names.

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

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

The description states a clear verb and resource: listing projects in the organization. It is understandable without opening the schema, but it does not explicitly distinguish this operation from sibling tools such as projects-retrieve or projects-duplicate.

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

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

Usage is implied by the phrase 'List the projects in the organization', which is appropriate for retrieval of all projects. However, the description does not state when to use this tool instead of projects-retrieve for a single project, nor does it mention any exclusions or edge cases.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description's one added fact is the required `projects:read` permission, which is genuinely useful auth context, but it says nothing about not-found behavior or what a successful response contains.

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

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

Two short sentences, front-loaded with the action. The opening line 'Get a project' duplicates the annotation title and the following sentence, a small redundancy, but nothing else is wasted.

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

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

Given a simple read-only tool with annotations covering safety and no output schema, the definition is adequate but thin: it omits what the returned project looks like and what happens when the ID is invalid or lacks permission.

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

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

Only one parameter exists and the schema already documents it as 'The ID of the project'; the description merely echoes 'by ID' with no format, source, or example. With near-complete schema text for the sole param, 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 ('Get') and resource ('a project') plus the lookup key ('by ID'), which cleanly separates it from projects-list, projects-create, and projects-update. It is clear but never mentions 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?

'by ID' implies the use case (single record fetch rather than list), but there is no explicit guidance on when to prefer this over projects-list or how to obtain the ID. Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds two genuinely useful facts: omitted fields retain their value (patch semantics) and the required scope. However, it never explains why the tool is flagged destructive, what is irreversibly lost, or what happens when an unknown id is passed.

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 then the two key constraints. The only waste is "Update a project" appearing twice, which reads as a title/body duplication artifact.

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 with no output schema, the description covers the partial-update contract and the authorization requirement, which is the minimum an agent needs. It is still thin on return behavior and failure modes, and the fact that the destructive flag is unexplained leaves an ambiguity an agent cannot resolve elsewhere.

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% at the top level — the `request` and `id` parameters are undocumented — and the description compensates with nothing about the request body or id format. The one semantic addition is "fields you leave out keep their value," which is helpful but does not cover the nested field set the schema already enumerates.

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

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

The verb and resource are clear ("Update a project"), so an agent knows the general action. But the sentence is essentially a restatement of the title and name, and it never says which fields are updatable or how this differs from siblings like projects-create, projects-duplicate, or projects-delete.

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 only usage condition given is the `projects:write` permission prerequisite. There is no guidance on when to call this versus projects-duplicate, projects-delete, or projects-retrieve, and no exclusions or preconditions 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered elsewhere. The description adds what kind of data comes back, but says nothing about the period default (30 days), how the aggregation window behaves, or response shape — and idempotentHint=false on a read tool is left unexplained.

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

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

Two short sentences with the payload description front-loaded and no filler. The opening 'Get queue statistics' mostly restates the name/title, a minor redundancy rather than bloat.

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 previews the returned metrics, which is the right call. But for a tool with a required nested request object and an unexplained time-window parameter, the definition leaves real gaps an agent would need to guess at.

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% and the tool wraps everything in a required nested 'request' object. The description's only nod to parameters is 'for a period', which does not clarify that withinDays defaults to 30 or that the schema permits negative values; the nested wrapper is undocumented in both places.

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

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

Specific verb+resource ('get queue statistics') plus an enumeration of the returned metrics (resolved/pending items, top reviewers, resolved per day), which naturally separates it from queue-list and queue-retrieve. It never explicitly names a sibling it should not be confused with, so it stops short of the top mark.

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: 'for a period' hints the tool answers aggregate questions about a queue, but there is no statement of when to prefer it over analytics-summary or queue-items-list, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context the annotations don't: the pending-only default, the inherited queue filters/date window, and that results are paginated. It says nothing about page size limits, ordering defaults, or what an item looks like.

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

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

Four short sentences, each carrying a distinct fact, with the default behavior front-loaded. Minor waste in restating the title as the first line.

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

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

No output schema exists, so the description would be the place to sketch the returned item shape, and it doesn't. Given the nested 13-parameter request and zero schema coverage, the definition is adequate to select the tool but thin for 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 description coverage is 0% across a nested request object with ~13 sub-properties (sort enum, labels, authorId, afterDate/beforeDate, includeResolved, conversationIds, filteredActionIds, page/pageSize). The description only hints that filters and a date window exist and that output is paginated; it never explains the enum values, the includeResolved toggle, or date formats. Substantial compensation is missing.

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 ('List the items of a review queue') and clarifies the scope: queue-level filters and date window applied, pending only by default. An agent can distinguish it from queue-list and queue-get-stats, though the differentiation is implicit 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?

Explicitly documents the default behavior (pending only) and routes the agent to queue-items-resolve/unresolve by noting the item `id` is used there. It does not say when to prefer queue-get-stats or queue-list, so the alternative guidance is partial rather than complete.

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

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

Annotations already disclose that this is a non-read-only, non-destructive, non-idempotent mutation. The description adds useful behavioral detail beyond that: the item leaves the pending list and a QUEUE_ITEM_COMPLETED webhook is sent, and it frames the operation as a dashboard check-off. It does not cover permissions or error behavior, so it is not a 5.

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

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

Three short sentences, front-loaded with the core action and followed by useful behavioral and alternative-tool context. No sentence is redundant.

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

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

For a simple mutation with annotations covering safety traits, the description supplies the important effect and side effect plus a clear alternative path. It does not address error cases or permission requirements, but no output schema exists and the remaining gap is minor.

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

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

The description does not mention any parameters, including id, itemId, or the project-scoping rules for projectId. The schema itself carries the parameter meanings for the nested request fields, so the schema is doing the heavy lifting and the description adds no parameter-level value.

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

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

The description states a specific verb and resource (resolve a queue item) and defines the effect clearly: the item leaves the pending list. It does not explicitly distinguish itself from siblings such as queue-items-unresolve or queue-items-resolve-many, 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?

It establishes when to use the tool as the equivalent of checking off an item in the dashboard, and it points the agent to POST /actions/execute when a moderation action is also needed. It does not explicitly say when to choose this over queue-items-unresolve, 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?

Goes meaningfully beyond annotations by disclosing the 100-item cap, that per-item semantics match the single resolve endpoint, and that partial success is possible—nonexistent IDs are skipped and reported in a notFoundIds field. It stops short of covering what happens to already-resolved items (relevant given idempotentHint=false) or whether resolution is reversible despite the queue-items-unresolve sibling.

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 scale, then the endpoint equivalence, then the edge-case behavior. Nothing is wasted or deferred to the end.

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 bulk mutation with no output schema, the description covers the essentials an agent needs to call it safely: batch limit, per-item behavior, and partial-failure reporting. Missing pieces—permission requirements and the effect on already-resolved items—are the only notable gaps.

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

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

The nested schema documents id, itemIds, and projectId in detail, so the description only needs to add limits—and it does restate the 100-item cap. However, the description adds nothing about itemIds format or the projectId key/name and project-key resolution rules, even though the top-level 'request' wrapper is itself undescribed.

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 (resolve queue items) and adds scope the name alone doesn't convey: bulk, up to 100 items in one request. It doesn't explicitly name the single-item sibling queue-items-resolve, but the 'in one request' phrasing implies the batch distinction clearly 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?

Usage is implied rather than stated: an agent can infer this is for bulk resolution and that queue-items-resolve exists for single items, but the description never says when to prefer one over the other or what preconditions apply. No exclusions or alternatives are spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description usefully adds the observable effect ('the item comes back in the pending list'), but says nothing about permission requirements, what happens to resolution metadata (who resolved it, when), or the error raised when unresolving an already-pending item. With annotations present the bar is lower, so a 3 fits.

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

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

Two short sentences: the effect is front-loaded, then an analogy that removes ambiguity. No filler or redundancy.

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

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

For a single-object mutation with no output schema, the definition conveys what happens to the item and that it is an undo of a resolve. It leaves gaps around error cases, permission level needed, and whether the item's prior resolution data is preserved — relevant for a non-idempotent mutation.

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

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

The top-level `request` object has 0% schema description coverage, and the description never names or explains any parameter — it only implies a queue and an item must be identified. The subtle projectId scoping rule ('required with an organization key unless the key reaches only one project') lives only in the nested schema and is not reinforced here.

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

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

States a specific verb (unresolve) and resource (queue item) and immediately clarifies the semantics with 'Mark a resolved item of a queue as pending again.' This clearly separates it from siblings queue-items-resolve and queue-items-resolve-many.

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 dashboard analogy ('same as removing a check-off') gives an unambiguous usage context and preconditions: the item must currently be resolved. It does not explicitly name the inverse sibling (queue-items-resolve) or state what happens if the item is already pending, 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 readOnlyHint=true, openWorldHint=false, idempotentHint=false, and destructiveHint=false, so safety behavior is largely covered. The description adds ordering (default queue first) and pagination, which are useful behavioral details, but it does not describe return fields or pagination parameters.

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

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

The description is short and front-loaded, with no padding. The repeated heading 'List queues' is slightly redundant with the tool name, but the remaining sentences are efficient and useful.

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

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

For a simple read-only list tool with rich annotations, the description covers the core operation, ordering, and pagination. However, with no output schema and low parameter documentation, it leaves gaps around response shape and how to use page/pageSize/projectId 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 reported as 0% and the description does not explain the request object, page, pageSize, or projectId. It only says the list is paginated, which hints at pagination but adds no meaningful syntax or constraint detail for the parameters an agent must supply.

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 project's review queues. It adds useful scope details (default queue first, paginated) but does not clearly distinguish itself from nearby siblings like queue-get-stats or queue-retrieve beyond pointing to GET /queue/{id} for counts.

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?

Implied usage is clear from the name and first sentence. The description gives one alternative for item counts via GET /queue/{id}, but it does not explicitly say when to use queue-list versus queue-items-list or queue-get-stats, and it references an endpoint rather than the sibling tool name.

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

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

Annotations already establish that this is a non-destructive read operation. The description adds a meaningful behavioral detail: the returned counts honor the queue's filters and date window, matching dashboard behavior. It does not cover auth or error behavior, but that is less critical given the annotations.

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

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

The description is short and front-loaded. The opening 'Get a queue' partly repeats the title, but the second sentence carries useful, non-obvious context about count semantics.

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

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

For a simple read-only retrieval tool with annotations and no output schema, the description covers the key behavioral nuance around counts. However, it leaves parameter usage and sibling selection unaddressed, so it is only adequately 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?

The description says nothing about the required queue ID or the optional projectId. Schema description coverage is reported as 0%, so the description should compensate for parameter meaning but does not. The nested schema does contain field-level descriptions, which prevents this from being a 1.

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 ('Get a review queue') and adds that the response includes item counts. It is clear enough to distinguish retrieval from list-type siblings, though it does not explicitly name queue-list or queue-get-stats as alternatives.

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 'Get a queue', but there is no explicit guidance on when to use this versus queue-list or queue-get-stats. The note about counts matching the dashboard clarifies the result semantics but 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 readOnly=false, idempotent=false, destructive=false and openWorld=false, so the mutation profile is covered. The description adds genuine non-annotation context: deliveries use the v2 envelope and are signed with the project signing secret, which tells an agent how consumers must verify payloads. It stops short of saying whether the secret is returned at creation time.

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?

Short and front-loaded, but the opening line 'Create a webhook' duplicates the title and is immediately restated by the next sentence ('Create a webhook subscribed to...'), so not every sentence earns its place.

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

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

Covers the creation act and delivery/verification behavior, but for a non-idempotent mutation with a nested payload and no output schema it omits what is returned (webhook id? signing secret?), whether duplicate URLs are allowed, and how event types map to delivery volume.

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?

Top-level schema description coverage is reported as 0%, and the description says nothing about the 'request' wrapper or the required eventTypes/name/url payload. The only parameter-adjacent sentence ('subscribed to one or more event types') restates what the schema's eventTypes description already says, so it fails to compensate 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: create a webhook subscribed to one or more event types. This clearly separates it from webhooks-list/retrieve/update/delete siblings by operation, though it never names them explicitly.

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

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

No guidance on when to create a webhook versus updating an existing one, no prerequisites, no mention of what the projectId requirement means in practice. The only pointer is 'see the signing secret endpoint', which is a routing hint rather than usage guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is fully carried by structured data. The description adds nothing beyond that, giving no information about irreversibility, what happens to delivery history or logs, or whether confirmation is required for a destructive operation.

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

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

It is short, but the single sentence is duplicated verbatim with no added information, which is pure waste rather than conciseness. Nothing is front-loaded because there is nothing to front-load.

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?

This is a destructive, non-idempotent mutation with a nested required object and no output schema, so the description was the only place to explain confirmation, irreversibility, and project scoping. It supplies none of that, leaving the definition inadequate for the tool's complexity.

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?

Top-level schema coverage is reported as 0% with a nested request object, so the description would need to compensate and does not. It never mentions the required webhook `id`, nor the `projectId` scoping rule, forcing the agent to read the nested schema to learn that projectId is required with an organization key.

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 is literally the tool title repeated verbatim ("Delete a webhook" twice), which is the definition of tautology against the name/title. An agent learns nothing about scope, and no sibling (webhooks-update, webhooks-retrieve) is distinguished.

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

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

There is no guidance on when to use this instead of webhooks-update or webhooks-retrieve, no prerequisites, and no note that deletion is permanent. The agent must infer the entire usage decision from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that results are paginated and project-scoped, which is genuinely useful behavioral context, but says nothing about result ordering, total counts, or pagination limits.

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

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

Two short sentences with no filler, and the core operation is front-loaded. The first line merely repeats the title, which is slight waste but harmless.

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

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

For a simple read-only list tool with annotation coverage this is close to adequate, but with no output schema the description should say more about what a webhook record or the paginated envelope contains. The nested 'request' object's page/pageSize semantics are left entirely to 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?

The schema reports 0% description coverage, and the description only indirectly signals the pagination parameters ('The list is paginated') and project scoping ('of the project'). It does not explain page defaults, pageSize bounds, or the nested 'request' wrapper, so it partially but not fully 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 the webhooks of the project'), which clearly separates it from sibling mutations like webhooks-create/update/delete. It doesn't explicitly contrast with webhooks-retrieve, so it stops short of full sibling differentiation.

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

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

No guidance on when to use this versus webhooks-retrieve, nor any prerequisites or exclusions. The list/paginated framing implies enumeration but leaves the agent to infer the choice.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that, such as handling of a missing/unknown ID, permission requirements, or whether the returned object includes secrets.

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?

Very short, but the first line 'Get a webhook' is pure duplication of the title and the second sentence repeats it again. Front-loaded, but one of two sentences earns nothing.

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

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

For a simple read with no output schema, the annotations cover safety and the schema covers the nested request shape. Still, nothing states what comes back or how a missing webhook is surfaced, which leaves the picture incomplete for an agent that must interpret the response.

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

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

Reported schema description coverage is 0%, so the description carries a compensation burden, yet it only echoes the 'by ID' notion already implied by the name. It says nothing about the nested projectId scoping rules, which are the most error-prone part of this call.

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 (retrieve) a webhook by ID. An agent can distinguish it from webhooks-list/create/update/delete by the verb alone. It doesn't explicitly contrast with webhooks-list, but the singular-by-ID framing is unambiguous.

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

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

There is no guidance on when to use this versus webhooks-list, or on prerequisites such as needing an ID obtained from the list call. The description just restates the operation; the agent must infer usage from the schema.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered externally. The description adds the v1 read-only constraint, but is silent on the behavior that matters most for a mutation: whether `body` replaces the entire webhook configuration or merges into it, and what happens to omitted fields such as eventTypes.

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?

Short, but wasted: "Update a webhook" appears twice as a heading and again as the opening sentence. The one genuinely useful sentence (legacy v1 handling) is buried behind that repetition instead of being front-loaded.

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

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

A destructive mutation with a nested object parameter, no output schema, and no permissions detail. The agent still cannot tell whether a partial body is safe, whether projectId is required for this key, or what a successful response contains, so the definition is under-specified for the complexity involved.

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?

Description says nothing about the `request` wrapper, the required `id`, or the optional `projectId` scoping rules. Schema description coverage is reported at 0% for the top-level parameter, so the description needed to compensate for nested-object ambiguity (partial vs full body) and does not.

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 plus resource ("Update a webhook"), which distinguishes it cleanly from webhooks-create, webhooks-delete and webhooks-retrieve in the sibling list. The legacy v1 caveat adds real scope information rather than restating the name.

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 when-not case (legacy v1 webhooks are read-only) and names the alternative workflow (delete, then create a new webhook). It stops short of stating when an update is preferable to recreating a v2 webhook, so it is clear context without full routing logic.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), and the description adds genuinely new behavior: words are embedded asynchronously in the background, progress is tracked via the embedding status endpoint, and policy attachment is required for moderation use. It does not mention rate limits or what the created object returns, but the async-embedding disclosure is substantial 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?

Four short sentences, front-loaded with the core action and followed by the important lifecycle facts (background embedding, policy attachment). The leading "Create wordlist" line merely repeats the annotation title and is the one wasted element.

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 never says what creation returns (the wordlist id/key) even though the agent needs that handle to poll wordlist-get-embedding-status. The async and policy requirements are covered, but the return-value gap for a create tool leaves it at minimum-viable-plus.

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?

Top-level schema description coverage is reported at 0% and the single `request` parameter is an undocumented nested wrapper, so the description has to carry weight. It does clarify that words are optional and can be supplied later, which maps to the `words` field, but it says nothing about `name`, `key` (including the auto-suffix behavior), or the `projectId` selector semantics.

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 wordlist in the organization") and implicitly separates itself from wordlist-words-add by noting words can be added now or later. It does not explicitly name sibling alternatives, so it stops short of a 5, but an agent can place it correctly in the wordlist 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?

"To use the wordlist in moderation, add it to a policy" gives the downstream prerequisite and "You can add words now or later" implies when this tool suffices versus wordlist-words-add. There is no explicit when-not guidance or named alternative, so usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds no behavioral context beyond the name, such as whether status is polled, what states exist, or whether the operation requires a specific project context.

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

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

The description is short and front-loaded, but the second sentence mostly repeats the first. It is concise yet under-informative, with redundancy rather than added value.

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

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

For a status-check tool with no output schema, the description should explain what the returned status contains and how to interpret progress. It does not, leaving the agent without enough context to use the result meaningfully.

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 does not mention the wordlist ID or projectId parameters at all. Schema description coverage is reported as 0%, so the description should compensate by explaining parameter meaning, but it provides no additional semantic guidance.

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

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

The description states a specific verb and resource ('Get embedding status' / 'Get the current embedding progress status for a wordlist'), but the second sentence largely restates the tool name. It does not distinguish this from sibling tools like wordlist-retrieve or explain what an embedding status actually includes.

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

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

There is no guidance on when to use this tool versus wordlist-retrieve, wordlist-list, or other wordlist operations. The description says what it does but not when an agent should choose it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that the list is paginated — but says nothing about page limits, total counts, or ordering, which matters for a paged listing.

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, but the first ('List wordlists') is a pure restatement of the tool name and title and earns nothing. The pagination note is front-loaded in the second sentence, which is the only substantive content.

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

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

For a nested-object tool with no output schema and zero parameter documentation, the description is thin: it never explains the project scoping model, pagination limits, or what a wordlist record contains. An agent would have to guess at the request envelope's semantics.

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 reported at 0%, so the description must compensate for the nested 'request' object's page, pageSize, and projectId fields — and it does not. The only schema-level documentation is on projectId, whose conditional-requirement nuance the description ignores entirely.

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 wordlists') plus the scope ('of the organization'), which distinguishes it from wordlist-retrieve and wordlist-words-add. It does not explicitly name a sibling as the alternative, keeping it just short of a 5.

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

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

There is no guidance on when to use this versus wordlist-retrieve or wordlist-get-embedding-status, and no prerequisites mentioned (e.g., that projectId may be required depending on the API key). The only hint is that results are paginated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structured data. The description adds nothing beyond that; a gap remains around failure behavior for invalid IDs and missing permissions.

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

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

Very short, but the first line 'Get wordlist' merely repeats the annotation title before the actual sentence restates it again, so a third of the text is redundant rather than 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?

For a nested-object, single-parameter lookup with no output schema, the description omits what a returned wordlist contains and how project scoping affects the call. Adequate only for a reader who already knows the API.

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 mentions only that lookup is 'by ID', which merely restates the required id field. The nested request object and the projectId parameter, including the important scoping rule for organization versus project keys, are never surfaced in the description; overall schema coverage is reported as 0%, so the description should have compensated and does not.

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

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

States a specific verb and resource: retrieve a single wordlist by ID. It is clear what the tool returns conceptually, but it never distinguishes itself from the sibling wordlist-list or wordlist-get-embedding-status.

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

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

No statement of when to use this versus wordlist-list (which presumably lists all wordlists) or wordlist-get-embedding-status. No prerequisites or error conditions are mentioned; the agent must infer the lookup use case from the name alone.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the description's job is to explain why. It does: sending words replaces all existing words and embeddings are recomputed asynchronously in the background, which is behavior an agent must know before calling. It omits permission requirements and whether the rewrite is recoverable.

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 the destructive replacement warning front-loaded. The only waste is the redundant first line repeating the tool title.

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, non-idempotent mutation with a nested request object and no output schema, the description covers the essential risks: partial-update default, total word replacement, and background embedding regeneration. It could add the project scoping requirement, but that is 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?

Reported schema description coverage is 0%, yet the description only adds the PATCH default (unsent fields unchanged) and word-replacement semantics. It says nothing about id, projectId scope rules, or the deprecated strict flag, leaving the agent to read the nested schema for the actual parameter contract.

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 a wordlist") and clarifies that the operation is a partial update. It implicitly separates itself from wordlist-words-add/wordlist-words-remove by explaining that sending words replaces the entire set, but it never names those siblings 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?

Usage is only implied: the patch semantics ("Fields that you do not send stay the same") hint this is the tool for editing key/name/description, while word replacement overwrites everything. It does not state when to prefer wordlist-words-add or wordlist-words-remove for incremental edits, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it doesn't say whether adding is additive vs. replacing, whether the wordlist must be non-empty, whether duplicates are silently ignored (the schema says so, the description does not), or what a partial failure looks like.

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

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

Two short sentences, front-loaded, nothing padded. But the second sentence is near-duplicative of the first, so it only barely earns its place — the sole new information is the word 'existing'.

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

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

For a mutation tool with no output schema, the description should disclose at least the duplicate-handling behavior (it is only in the schema), whether the call is additive to existing words, and any limit on the words array. With a nested request object and no return-value documentation, the description leaves meaningful gaps an agent must guess at.

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 contributes zero parameter meaning; everything useful sits in the nested schema (id = wordlist to add to, words = array with duplicates ignored, projectId = detailed project scoping rules). Because the nested schema is reasonably self-documenting, the baseline 3 applies, though the top-level 'request' wrapper itself is undocumented anywhere.

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

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

The verb+resource ('Add words to wordlist') is unambiguous and the second line narrows it to an *existing* wordlist, which is real information. However, the first line is essentially a restatement of the tool name, and nothing distinguishes it from siblings like wordlist-create, wordlist-words-remove, or wordlist-update. Purpose is clear but no differentiation is offered.

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?

'existing wordlist' implies a prerequisite (the wordlist must already exist), which is a sliver of usage context. But there is no guidance on when to use this versus wordlist-create (new list) or wordlist-words-remove, no mention of what happens on duplicate or unknown words, and no error/precondition 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, idempotentHint=false and readOnlyHint=false, so the description carries a lower bar, but it still adds nothing: no mention of irreversibility, no partial-versus-atomic failure semantics for an array of words, and no note that a missing word may or may not error. For a destructive batch mutation this is a meaningful gap.

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

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

The description is two sentences that say the same thing twice ("Remove words from wordlist" / "Remove words from an existing wordlist"), wasting the entire budget on redundancy. Brevity here reflects under-specification rather than efficient communication.

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 destructive, non-idempotent, nested-object tool with no output schema needs more than a duplicated title. There is nothing about failure modes, partial application, or confirmation requirements, leaving the agent to reconstruct behavior from the schema and annotations alone.

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

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

The description names no parameters at all, and reported schema description coverage is 0% for a nested request object containing id, words and projectId. The agent must infer that `words` is a batch removal and must open the schema to learn that projectId is conditionally required depending on key scope.

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 verb and resource ("Remove words from wordlist") so the basic action is identifiable, but it is little more than a restatement of the tool name. It gives no indication of how it differs in effect from the sibling wordlist-words-add, beyond the obvious add/remove polarity.

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

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

There is no guidance on when to use this versus wordlist-words-add or wordlist-update, no prerequisites, and no mention of what happens when a supplied word is absent. The only usage signal is carried by the tool name itself, not the description.

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