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

Annotations already declare openWorldHint=true and destructiveHint=false; the description adds real value on top by disclosing that DMs reach real people (a social/irreversible side effect), and by naming two concrete failure modes: 409 on duplicate keyword for the same posts and keyword_limit_exceeded when the plan has no free active-keyword slot. Missing are what gets returned on success and any permission/scope requirements, which keeps it off a 5.

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

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

Three sentences: what it does, the caution about real recipients, then failure modes — front-loaded and ordered by what the agent needs first. No restatement of the title and no filler.

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

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

For an 11-parameter mutation tool with no output schema, the description covers purpose, side-effect caution, and error paths, which is most of what's needed. It stops short of saying what the successful call returns (presumably the created keyword with an id) or noting that the new keyword counts against the plan limit, which an agent creating keywords in bulk would want to know.

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

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

Schema description coverage is 100% and every one of the 11 parameters is documented in detail in the schema, so the schema does the heavy lifting. The description only adds a passing reference to the optional public reply, offering essentially no parameter meaning beyond structured data — baseline 3 is appropriate.

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

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

States a specific verb and resource (create a comment-to-DM automation) and goes further to explain the actual mechanism: a comment triggers the keyword and CommentKeyword sends the DM, optionally with a public reply. That mechanism makes it unambiguously distinct from the list/get/update/delete_keyword siblings without naming 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?

Gives a clear precondition for use — confirm details with the user first, because it messages real people — which is genuinely actionable guidance for an agent. It does not explicitly contrast with update_keyword (e.g. 'use this only for new keywords; to change an existing one use update_keyword'), so the when-not case is left 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?

It adds crucial behavioral context beyond the annotations by detailing a multi-step conversational workflow: the first call returns a confirmation requirement, which then necessitates a second, conditional call using the 'confirm' parameter.

Agents need to know what a tool does to the 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 highly condensed yet comprehensive, front-loading the operational alternative ('Prefer update_keyword...') before detailing the complex, conditional deletion flow.

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

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

Given the destructive nature and the multi-step conversational requirement (waiting for confirmation), the description provides maximum possible context without needing an output schema.

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

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

While the schema defines 'confirm' as a boolean, the description provides the essential semantic context, explaining that it must only be set to true after a specific DELETE_CONFIRMATION_REQUIRED response is received.

Input schemas describe structure but not intent. Descriptions should explain 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 explicitly states the purpose (permanently delete a keyword automation) and effectively distinguishes this tool from the sibling update_keyword tool.

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

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

It provides explicit guidance on when to use this tool versus the alternative, stating that users should 'prefer update_keyword with isActive false' to pause the keyword.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds one piece of behavioral context beyond that: the response includes whether the automation is still waiting for the next post (nextPostStatus). It says nothing about error behavior for an unknown/invalid id or the rest of the returned shape.

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

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

One sentence with zero filler, front-loading the verb and resource and appending the most notable returned field. Nothing to remove.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a full annotation safety profile and no output schema, the description covers what it does and highlights a key returned field. Slightly richer return-value context would be needed for a 5 given the lack of an output schema.

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

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

Schema description coverage is 100% and the single 'id' parameter is documented as the keyword publicId with UUID format. The description's 'by its publicId' simply echoes the schema, adding no format, lookup, or failure semantics beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get one keyword automation') and explicitly scopes it to a single item, which implicitly separates it from the sibling list_keywords. It stops short of explicitly naming or contrasting with list_keywords, so it is clear but not maximally differentiated.

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

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

The phrase 'by its publicId' implies you must already know the identifier, which hints at when this is appropriate versus a list call, but the description never states when to use this instead of list_keywords or what to do if the id is unknown. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true; the description adds the non-obvious constraint that agents cannot be created or edited through this API (dashboard-only) and that only 'Live' agents are usable downstream. It does not cover pagination or failure behavior, so 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?

Two sentences, purpose front-loaded, second sentence carrying only the chaining instruction. No filler or repetition of the 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?

With no parameters and no output schema, the description supplies enough: what it returns (identifiable agents via publicId), which agents matter (Live), and how to use them. It doesn't describe the response shape or ordering, which is a minor gap given no output schema exists.

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

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

The tool takes zero parameters, so the baseline is 4. The description instead adds return-semantics value by identifying that results carry a publicId and a Live status that feeds other tools.

Input schemas describe structure but not intent. Descriptions should explain 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 AI agents already set up in the workspace') and immediately distinguishes itself from the keyword siblings by noting agents are created and edited in the CommentKeyword dashboard, not here. An agent can tell this is a read-only enumeration of agents versus the keyword CRUD 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?

Gives a concrete next step: pass the publicId of a Live agent as aiAgentId to create_keyword or update_keyword so it keeps chatting. That implicitly covers the main reason to call it, but there is no explicit 'do not use this to create/manage agents' exclusion, so it stops short of full 5-level 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?

readOnlyHint=true and openWorldHint=true already establish the safety profile, so the description only needs to add context. It contributes the result ordering (newest first), which is useful, but says nothing about pagination behavior, result count limits, 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?

Two short sentences, with the resource and ordering front-loaded and the usage hint immediately after. Nothing is wasted.

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

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

For a listing tool with four optional filters and no output schema, the description leaves the return shape and most filter semantics unstated. It is adequate to identify the tool, but not to invoke it with confidence around paging or filtering.

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

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

Schema coverage is only 50%, and the description mentions no parameters at all. The undocumented offset and status filter have no explanation anywhere, and limit/search only get one-line schema notes, so the description does not 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 comment-keyword automations), the scope (workspace), and the ordering (newest first). This cleanly separates it from get_keyword (single fetch) and the create/update/delete siblings.

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

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

"Use it to check whether a keyword already exists before creating one" gives a concrete trigger that points at the create_keyword workflow. It gives no explicit when-not or pagination guidance, but the primary usage context is clear.

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

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

Annotations already declare this a non-destructive, idempotent, open-world write. The description adds value beyond them: it discloses PATCH semantics, that array fields wholesale-replace existing variants (not merge), and that isActive=false pauses. It does not mention permission requirements or whether pausing affects in-flight DMs, which keeps it off a 5.

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

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

Four short sentences, zero filler, front-loaded with the update-semantics that matter most (partial change, re-targeting, array replacement, pausing). Every sentence carries a distinct behavioral fact.

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

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

For a 12-parameter mutation with no output schema, the description covers the highest-risk surprises (silent array replacement, re-targeting side effect, pause semantics) while the rich schema handles field detail. The remaining gap is return behavior — nothing says what the response contains after the update — which is minor given the tool's straightforward 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 coverage is 100%, so the schema already documents all 12 parameters thoroughly, establishing the baseline of 3. The description does add meaning beyond the schema — that passing target re-targets (including the next_post reset case) and that dmMessages/commentReplies replace rather than append — but it covers only 3 of the 12 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 opening sentence names a specific verb ("Change") and resource ("keyword automation"), and the immediate follow-up "Only the fields you pass change" pins the operation as a partial update rather than a full replace. It is clearly distinguishable from create_keyword/delete_keyword/get_keyword by name alone, though no sibling is explicitly named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 (modify an existing automation) but never stated as a when-to-use rule, and no alternative is named — e.g. nothing says to use create_keyword for new automations or get_keyword to inspect before changing. The field-level guidance about retargeting and pausing is helpful but is operational detail rather than tool-selection guidance.

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