Social Media MCP by Publinio

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

The annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context beyond them: activation triggers recurring generation with credit caps and, crucially, 'Previously approved automatic delivery can publish to connected channels' — an external side effect the agent would not otherwise anticipate. It does not address permissions or rate limits, 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?

Three short sentences, front-loaded with the activation action, and each carries information. 'Only advertising artwork' is slightly clipped in phrasing but costs no space. No padding.

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

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

An output schema exists, so return values need not be described, and the annotations carry the safety profile. What remains missing is the prerequisite chain (prepare/resume siblings) and any meaning for the four required parameters, which for a destructive activation tool is a real gap.

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

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

Schema description coverage is 0% and all four parameters (brandId, automationId, revision, idempotencyKey) are required with no descriptions. The description never explains any of them — notably the concurrency meaning of 'revision' (an exclusiveMinimum integer) or the 8-128 character idempotencyKey — 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 (activate) and resource (recurring generation via the saved recipe/credit caps), and scopes it with 'Only advertising artwork; the saved automation type must match this tool.' That constraint is what separates it from the ~20 sibling activate_* automation tools. It stops short of naming a specific sibling, so it lands at 4 rather than 5.

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

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

The line 'the saved automation type must match this tool' gives an implied precondition for use, but there is no explicit guidance on when to activate versus resume_ad_creative_builder_automation or pause_automation, nor any mention that a saved automation must first exist (prepare_ad_creative_builder_automation). Usage is inferable but not stated.

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

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

Annotations already declare write, destructive, idempotent, and open-world. The description adds valuable context beyond that: credit caps are consumed, previously approved automatic delivery can publish to connected channels (an external side effect), and only background-removed images are eligible. Missing auth/permission details, but strong 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?

Three tight sentences, front-loaded with the action and its purpose. Every sentence adds either behavior or a constraint. Minor awkwardness in 'Previously approved automatic delivery can publish to connected channels' but no filler.

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

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

With a rich annotation set and an output schema, the description need not cover return values. It covers domain constraint and delivery behavior, but leaves parameter meaning and activation prerequisites unexplained, which matters for a 4-parameter mutation tool with 0% schema coverage.

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 description mentions no parameter names or semantics. It does not explain brandId, revision, or idempotencyKey, and only loosely implies that a saved automation (automationId) is needed. No compensation 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 the specific action (Activate) and resource (recurring generation using the saved recipe), and distinguishes itself from the many sibling activate_* tools by requiring 'the saved automation type must match this tool' and constraining to 'Only images with backgrounds removed'. It does not name a specific alternative sibling, so not 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?

Implies usage via the constraint that the saved automation must be of the background-removal type, but never states when to use this versus prepare_, pause_, or resume_ variants, nor any prerequisites like having a prepared sample. No explicit when-not guidance.

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

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

Annotations cover the safety profile (destructive, idempotent, openWorld), so the bar is lower. The description adds real context beyond them: credit consumption via 'credit caps' and that previously approved automatic delivery can publish to connected channels — meaningful for a destructive, outward-facing mutation.

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. Some phrasing ('the saved automation type must match this tool') is slightly cryptic, but there is little 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?

An output schema exists so return values need not be explained, and annotations carry the safety profile. However, for a destructive 4-param mutation with zero schema coverage, the omission of parameter meaning (especially revision and idempotencyKey) leaves it only minimally complete.

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

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

Schema description coverage is 0% and all four required params (brandId, automationId, revision, idempotencyKey) are undocumented. The description vaguely references 'the saved recipe' and matching automation type but never explains revision or the idempotency key, so it 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: activate recurring generation from a saved recipe. The clause 'Only banner artwork; the saved automation type must match this tool' implicitly distinguishes it from the ~20 sibling activate_* tools for other artwork types, though it never names a specific sibling.

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 saved automation type must match this tool' — use it for banner-generator automations. But there is no explicit when-to-use/when-not guidance, and no differentiation from resume_*, pause_*, or prepare_banner_generator_automation.

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=true, and openWorldHint=true. The description adds meaningful behavioral context beyond annotations: it uses credit caps, can publish to connected channels (an external side effect), is limited to written campaign sections, and requires a matching automation type.

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

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

The description is three front-loaded, terse sentences with no filler. It could be slightly clearer, but every sentence contributes information about purpose, behavior, or constraints.

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, idempotent mutation tool with 4 required parameters and 0% schema description coverage, the description is incomplete. It does not explain the parameters, does not clarify what happens on type mismatch, and does not mention usage alternatives, though the presence of an output schema and safety annotations reduces the overall burden.

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 there are 4 required parameters (brandId, automationId, revision, idempotencyKey). The description mentions none of them by name or explains their meaning, formats, or constraints, leaving the agent with no semantic guidance for any 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 states a specific verb (Activate) and resource (recurring generation using the saved recipe), and ties it to written campaign sections and a matching automation type. This differentiates it from other activate_* tools implicitly, though it does not name alternatives explicitly.

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

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

The description provides a precondition (saved automation type must match) and a scope (only written campaign sections), but offers no guidance on when to use this tool versus related siblings like resume_*, pause_*, or prepare_*. No alternatives or exclusions 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?

Adds context beyond the annotations: it reveals that activation enables a recurring generation loop and that 'previously approved automatic delivery can publish to connected channels,' an outward-facing side effect that aligns with openWorldHint/destructiveHint but is not obvious from them. It also implies credit consumption via 'credit caps.' It does not, however, describe failure modes or what the activation toggles internally.

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 scoping constraint, with no filler. It is tighter than most descriptions in this family, though the middle sentence on automatic delivery is slightly tangential to calling the tool.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains missing for a 4-param mutation is any parameter guidance (notably revision and idempotencyKey) and any statement of prerequisites such as having a saved automation of the matching type. Adequate but with clear gaps.

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

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

With four required parameters and 0% schema description coverage, the description carries the full burden of explaining them, yet it never maps brandId, automationId, revision, or idempotencyKey to meaning. In particular the revision (concurrency) and idempotencyKey semantics are left entirely unexplained, which matters for a mutation 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 (activate) and resource (recurring generation using the saved recipe and credit caps), and explicitly bounds scope with 'Only captions and hashtags; the saved automation type must match this tool.' This lets an agent distinguish it from the 20+ sibling activate_* tools without opening any schema.

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

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

The condition 'the saved automation type must match this tool' plus 'Only captions and hashtags' gives a clear routing rule for when this tool applies versus other activate_* variants. It stops short of naming alternatives (e.g., prepare_* or resume_*) or stating exclusions explicitly, so it is strong but not fully prescriptive.

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, destructive=true, idempotent=true, openWorld=true, so the safety profile is partly covered. The description still adds real behavior beyond them: credit-cap consumption, that approved delivery may publish to connected channels (external side effect), and the automation-type match constraint. It does not explain what is destroyed or what authorization is required, leaving a small gap.

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

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

Three short, front-loaded sentences that open with the action and avoid padding. The final clause ('Only written carousel sections') is cryptic and slightly ambiguous, but the overall structure is efficient.

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

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

An output schema exists so return values need not be described, and the annotations carry the safety profile. However, for a destructive, open-world mutation with four fully undocumented required parameters, the description omits prerequisites, permission needs, and what the revision/idempotencyKey guards against.

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 description never maps meaning to brandId, automationId, revision, or idempotencyKey. The concurrency-control semantics of revision and the replay-safety purpose of idempotencyKey are entirely undocumented in both places, so the description 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 clear verb (activate) and resource (recurring carousel generation using the saved recipe and credit caps). It distinguishes itself from the activate_*_automation siblings by scoping to carousel sections and requiring the saved automation type to match, though it never names a specific sibling or the prepare_* counterpart.

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 saved automation type must match this tool' hints at a prerequisite (a previously prepared carousel automation) but there is no explicit when-to-use, when-not-to-use, or routing to prepare_carousel_creator_automation / pause / resume siblings. An agent must infer the workflow from the name.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered; the description then adds genuinely new behavior — that previously approved automatic delivery will publish to connected channels, and that credit caps govern spend. It omits reversibility details (e.g., how to stop publishing, whether re-activation double-charges), which keeps it at 4.

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

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

Three short sentences with the core action front-loaded and no filler. The clause 'Only edited source images' is terse to the point of ambiguity, but the overall structure is tight and readable.

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?

An output schema exists, so return values need not be described. For a destructive, externally-publishing mutation the description covers the side effect and the type-match constraint but omits prerequisites (prior sample approval, prepared automation), the role of revision/idempotencyKey, and failure modes — leaving real gaps.

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

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

Schema description coverage is 0% across 4 required parameters, so the description must carry the meaning, and it largely does not. Only automationId is indirectly covered via 'the saved automation type must match this tool'; brandId, revision, and idempotencyKey are never explained, so the agent has no guidance on how revision or the idempotency key affect the 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 (activate) and resource (recurring generation from a saved recipe), and the last clause ties it to the edit-image automation type, which helps separate it from the many sibling activate_*_automation tools. It stops short of naming a specific alternative like resume_ or prepare_, but the action is unambiguous.

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

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

Implies prerequisites ('saved recipe', 'the saved automation type must match this tool') so an agent can infer the automation must already exist and be of the edit-image flavor. It never explicitly says when to prefer activate over resume_/pause_/prepare_ or what state the automation must be in beforehand.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true. The description adds useful context: recurring generation, credit caps, and that previously approved automatic delivery can publish to connected channels (a side-effect worth noting). This adds some value beyond annotations, but doesn't explain the destructive/idempotency behavior or what credit caps entail, so it's moderate.

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 concise sentences, front-loaded with the core action. No wasted words, though the final sentence could be integrated more cleanly.

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?

Since an output schema exists, the description needn't explain returns. It covers the action, the type-match precondition, and the publishing side-effect, which is reasonably complete for a mutation tool with annotations carrying the safety profile. However, it omits credit-cap specifics and any parameter guidance for a 4-required-param, 0%-coverage schema.

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

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

Schema coverage is 0% and there are 4 required params, but the description provides no meaning for brandId, automationId, revision, or idempotencyKey. The schema itself has patterns/constraints that imply usage. Baseline for low coverage would push higher, but the description fails to compensate for any of the 4 params, so 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 (Activate) and resource (recurring generation via the saved automation recipe), and scopes the tool to image backgrounds with the constraint that 'the saved automation type must match this tool'. This differentiates it from siblings like activate_recolor_automation or activate_image_generator_automation, though the differentiation is implied through the type-match note rather than explicit 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?

It implies usage via 'the saved automation type must match this tool' and 'Only replacement image backgrounds', giving a precondition. But it doesn't explicitly state when to use this versus the many sibling activate_* tools, nor when not to use it.

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

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

Annotations already declare the safety profile (destructive, idempotent, open-world, non-read-only), so the bar is lower. The description does add real context beyond them: activation creates a recurring job that can publish to connected channels and is bounded by credit caps, and it only applies to enhanced source images. It stops short of explaining what the destructive/idempotent hints mean in practice, e.g. what credits are consumed or whether activation is reversible.

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

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

Three dense sentences with no filler, and the core action leads. Some phrasing is telegraphic ('Only enhanced source images'), which slightly hurts readability but not length.

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?

Output schema exists, so return values need no explanation, and the description covers purpose plus two preconditions. The gap is the four undocumented required parameters and what activation actually changes in the account (recurrence cadence, channel publishing scope), which an agent needs before calling a destructive, non-read-only tool.

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

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

All four parameters (brandId, automationId, revision, idempotencyKey) are required with 0% schema description coverage, so the description carries the full burden. It alludes to a 'saved recipe' and matching automation type, loosely implying automationId, but says nothing about brandId, the revision/optimistic-concurrency field, or how idempotencyKey behaves on retry.

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

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

The description names a specific verb and resource ('Activate recurring generation'), which distinguishes it from pause_/resume_ siblings, and 'the saved automation type must match this tool' implicitly routes it against the ~20 other activate_* variants. However, it never names image enhancement explicitly as the automation family in the prose, relying on the tool name for that 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?

Preconditions are stated ('the saved automation type must match this tool', and that delivery must have been previously approved), which implies when activation is appropriate. But there is no explicit contrast with resume_image_enhancer_automation, pause_automation, or prepare_image_enhancer_automation, so the agent must infer the lifecycle position on its own.

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=true, so the mutation and retry model is covered. The description adds genuine context beyond that: activation is bounded by 'credit caps', and 'previously approved automatic delivery can publish to connected channels' discloses an external side effect (channel publishing) the annotations only hint at via openWorldHint.

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 no filler. The third sentence is terse to the point of ambiguity ('Only original generated images'), but it earns its place as a scope limit.

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?

An output schema exists so return values need no explanation, and annotations cover safety. The description adequately covers scope, credit limits, and channel side effects, but with 0% schema coverage on four required parameters and no mention of the prepare/approve prerequisite workflow, an agent still lacks the full picture for correct invocation.

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

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

Schema coverage is 0%, so the description must carry the parameter burden for 4 required fields. It vaguely references 'the saved recipe' and 'saved automation type', which loosely point at automationId, but brandId, revision, and especially idempotencyKey (critical for a mutation with idempotentHint) are entirely unexplained.

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

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

States a specific verb (activate) and resource (recurring generation from a saved recipe), which distinguishes it from resume_*, prepare_*, and update_* siblings. The clause 'the saved automation type must match this tool' routes it within the large activate_* family, though it never names the image-generator recipe explicitly as the required match.

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 constraint 'the saved automation type must match this tool' is an implied precondition for use, and 'using the saved recipe' implies a prior prepare/approve step. However, the description never states when to use activate versus resume_* or update_image_generator_automation, leaving the agent to infer the activation lifecycle.

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=true and openWorldHint=true, so the bar is lower, and the description still adds real context: activation consumes 'credit caps', it can cause 'previously approved automatic delivery' to publish to connected channels, and it emits only logo concepts. It does not explain what the destructive aspect actually destroys or what authorization is required.

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

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

Three compact sentences with the action front-loaded and no filler; each clause carries information (purpose, side effect, type constraint). The phrasing is slightly terse to the point of ambiguity, but nothing is wasted.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, for a destructive, credit-consuming activation with four undocumented required parameters, the description leaves key operational questions (permissions, what happens on repeat calls, version/revision mismatch behavior) unanswered.

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% with four required parameters, so the description carries the full burden, yet it only obliquely alludes to the automation ('saved recipe', 'the saved automation type') and says nothing about brandId, revision, or idempotencyKey. An agent gets no help understanding that revision is a version guard or that idempotencyKey deduplicates repeat activations.

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 ('Activate') plus the resource ('recurring generation') and constrains it to generated logo concepts, so an agent can place it among the many activate_* siblings. The closing clause ('the saved automation type must match this tool') reinforces the domain restriction, though it never names an alternative tool explicitly.

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

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

It implies usage ('activate recurring generation using the saved recipe') but gives no when/when-not guidance against the obvious alternatives: resume_logo_maker_automation, prepare_logo_maker_automation, update_logo_maker_automation, or pause. No prerequisites such as requiring a prepared/approved automation 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 destructive=true, idempotent=true, openWorld=true, readOnly=false, so the safety profile is covered. The description adds non-obvious behavioral context: activation starts recurring generation, is bounded by credit caps, and can cause previously approved delivery to publish to connected channels. The type-matching precondition is also useful. It stops short of saying how to reverse the activation or what the run cadence 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 with the action and scope front-loaded and no filler. The middle sentence about automatic delivery is the only one that could arguably be tightened, but it carries real behavioral 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?

An output schema exists, so return values need not be described. For a destructive, open-world mutation, the description usefully discloses the publishing side effect and the type-match precondition, but the four required parameters remain opaque, leaving the agent unable to construct a correct call 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?

Schema description coverage is 0% with four required parameters (brandId, automationId, revision, idempotencyKey), and the description supplies no per-parameter meaning. Terms like 'saved recipe' loosely gesture at automationId, but revision and idempotencyKey semantics are entirely undocumented in both schema and description, 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 (activate) and resource (recurring generation from a saved recipe), and narrows it with 'Only written social posts; the saved automation type must match this tool.' That last clause is a genuine attempt at sibling differentiation, though it doesn't name the sibling by 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?

Implies when to use: a saved recipe exists and the automation type is 'written social posts.' It notes that previously approved automatic delivery can publish to connected channels, which hints at prerequisites. But it never names the alternatives it sits among (resume_*, pause_automation, prepare_post_writer_automation), so the routing inference is left to the agent.

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

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

Annotations already cover readOnly=false, idempotent=true, destructive=true, openWorld=true, so the bar is lower. The description still adds real value: it discloses that activation is recurring, consumes 'credit caps', and that previously approved automatic delivery can publish to connected channels — a genuine side effect beyond the safety flags.

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 scope constraints. No filler, though the middle sentence about automatic delivery is slightly disconnected in 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?

An output schema exists, so return values need not be described, but the four required parameters are fully undocumented at 0% coverage in both schema and prose. For a destructive, state-changing activation tool this leaves a noticeable gap.

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

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

Schema description coverage is 0% and the description never explains brandId, automationId, revision, or idempotencyKey. It vaguely alludes to a 'saved recipe'/'saved automation type' (automationId) but adds no format, revision-checking, or idempotency semantics, so it fails to compensate for the documentation 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 ('Activate') and resource ('recurring generation using the saved recipe and credit caps'), and scopes it via 'Only enhanced product images; the saved automation type must match this tool.' This differentiates it from the product_staging or retouch siblings, though it never names a sibling explicitly.

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

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

The 'saved automation type must match this tool' line implies this is the correct tool only for product-beautifier automations, and 'Previously approved automatic delivery' hints at an approval prerequisite. However, it gives no explicit when-to-use vs. resume_/pause_/update_product_beautifier_automation 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=true, openWorldHint=true and non-read-only, so the safety profile is partly covered. The description adds real value beyond that: generation consumes credit caps, and 'previously approved automatic delivery can publish to connected channels' discloses an external side effect the annotations only imply via openWorld. It stops short of stating irreversibility or permission requirements.

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

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

Three short sentences, front-loaded with the action and followed by preconditions and side effects; nothing is redundant. The telegraphic fragment 'Only staged product images' is terse but earns its place as a scoping rule.

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?

An output schema exists so return values need no explanation, and the description covers preconditions, credit usage, and publication side effects. Still, for a destructive four-parameter mutation with zero schema coverage, the absence of any parameter-level guidance leaves the definition only partially complete.

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

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

Schema description coverage is 0% for four required parameters, so the description carries the full burden and largely fails it. 'Saved recipe' loosely maps to automationId and 'saved automation type must match' hints at validation, but brandId, revision, and idempotencyKey are never explained, leaving most of the input contract undocumented.

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

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

States a clear verb+resource ('Activate recurring generation using the saved recipe') and scopes it with constraints ('only staged product images', 'automation type must match this tool'), which distinguishes it from prepare_* and pause_* siblings. It never explicitly contrasts with resume_product_staging_automation, so the boundary against that nearest sibling must be inferred.

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?

Preconditions are given ('saved recipe', 'saved automation type must match this tool', 'only staged product images'), which implies usage. However, there is no explicit when-to-use vs when-not-to-use, and no routing to alternatives such as resume_ or pause_automation for an already active or stalled automation.

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=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context beyond that: activation consumes 'credit caps' and 'previously approved automatic delivery can publish to connected channels', a real side effect an agent must weigh before calling. It does not explain revision-conflict or idempotency-key replay behavior, which keeps it short of a 5.

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

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

Three short sentences, no filler, with the core action front-loaded and the precondition last. Every sentence carries information; nothing is repeated from 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?

An output schema exists, so return values need no explanation, and the annotations cover mutability and idempotency. The description supplies the two things an agent most needs for a destructive activation call — the credit cost and the possibility of publishing to connected channels — but leaves the four parameters, especially revision and idempotencyKey, 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 0%, so the description carries the full burden for four required parameters, and it effectively documents none of them by name. 'Saved recipe' loosely gestures at automationId and 'must match this tool' hints at a type constraint, but brandId, revision, and idempotencyKey are never mentioned, leaving their meaning to be guessed from the schema patterns.

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 ('Activate recurring generation') and resource ('saved recipe'), and the closing clause 'the saved automation type must match this tool' differentiates it from the twenty-plus sibling activate_* tools. The recolor-specific scope ('Only recolored source images') is stated explicitly, though it is only marginally more informative than the name itself.

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

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

The description implies when to use it — activating an already-prepared recolor automation — and states a precondition ('the saved automation type must match this tool'). However, it never names alternatives such as resume_recolor_automation, pause_automation, or prepare_recolor_automation, so the agent must infer the lifecycle position rather than being told 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 destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the mutation/side-effect profile is partly covered. The description adds real value by disclosing that approved automatic delivery can publish to connected channels and that credit caps are consumed. It does not explain what makes activation destructive or how to reverse it.

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

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

Three short sentences, front-loaded with the action and effect. No filler, though 'Only written reel concepts' is awkwardly worded and slightly opaque.

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?

An output schema exists, so return values need no explanation, and the description covers the main behavioral concerns (publishing, credit consumption, type matching). The significant gap is the complete absence of parameter semantics for a 4-required-param mutation tool.

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

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

Schema description coverage is 0% and all four parameters (brandId, automationId, revision, idempotencyKey) are undocumented in the schema. The description only loosely gestures at automationId via 'the saved automation type must match this tool' and never addresses revision or idempotencyKey, 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?

The description states a specific verb+resource: 'Activate recurring generation using the saved recipe and credit caps.' It also scopes the tool ('Only written reel concepts; the saved automation type must match this tool'), which distinguishes it from the many sibling automation tools. It stops short of naming the closest siblings (resume_/prepare_reel_concepts_automation), so it is clear but not fully disambiguating.

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?

'Activate recurring generation' implies when to use it, and 'the saved automation type must match this tool' is a light precondition. However, there is no explicit guidance on when to activate vs. resume, prepare, or pause the same automation, all of which exist as siblings. Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=true, so the safety profile is partly covered. The description adds meaningful context beyond them: previously approved automatic delivery can publish to connected channels, and credit caps apply — disclosing the concrete downstream consequence and cost dimension of activation.

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

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

Three compact sentences that are front-loaded with the activation purpose, followed by consequence and constraint. No filler, though the third sentence packs two distinct constraints that could be separated for clarity.

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?

An output schema exists, so return values need not be described. For a destructive mutation tool this is adequate on behavior, but the near-total absence of parameter guidance at 0% schema coverage leaves the agent under-informed about revision and idempotencyKey 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 0% across four required parameters (brandId, automationId, revision, idempotencyKey), so the description carries the full burden and largely fails. 'Saved recipe' loosely gestures at the automation reference, but revision, idempotencyKey, and brandId receive 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 ('Activate recurring generation using the saved recipe'), and adds scope constraints ('Only retouched source images') plus a discriminator against the large activate_* sibling cluster ('the saved automation type must match this tool'). It does not explicitly name a sibling like prepare_retouch_automation, so differentiation is present but not sharp.

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

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

Provides a precondition ('saved automation type must match this tool') and a scoping rule (only retouched source images), which implies when it applies. However, it gives no guidance on when to choose this over prepare_retouch_automation, resume_retouch_automation, or update_retouch_automation, leaving the agent to infer the alternative.

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

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

Annotations already declare destructive=true, idempotent=true, and openWorld=true. The description adds genuine context beyond them: activation consumes credits ('credit caps') and previously approved delivery can publish to connected channels, explaining the open-world side effect. It stops short of stating reversibility or retry semantics for the idempotency behavior.

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

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

Three compact sentences with the core action front-loaded and the type-match constraint at the end for emphasis. No filler, though the delivery sentence is slightly tangential to activation itself.

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?

An output schema exists so return values need not be explained, and annotations cover the safety profile. However, for a mutation tool with four undocumented required parameters and a prepare/activate workflow in the sibling set, the description omits prerequisites (e.g., whether the automation must first be prepared or approved) and any parameter detail.

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 4 required parameters (brandId, automationId, revision, idempotencyKey), and the description names none of them. 'Saved recipe' and 'credit caps' gesture at the recipe/revision concept but add no syntax, format, or meaning for any argument, so the description 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+resource (activate recurring generation) and adds a scoping constraint — 'Only resized source images; the saved automation type must match this tool' — which lets an agent distinguish it from the many other activate_* siblings. It stops short of naming a competing sibling or stating a hard boundary condition.

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 ('Activate recurring generation using the saved recipe') and the type-matching constraint hints at when this tool is appropriate, but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as resume_* or the prepare_/update_ counterparts. Usage is inferred 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 readOnlyHint=false, idempotentHint=true, destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description still adds genuine context: that previously approved automatic delivery can publish to connected channels (external side effect) and that credit caps govern consumption. Return format is not described but an output schema exists.

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

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

Three tight sentences with the core action front-loaded, followed by the side-effect note and the scoping constraint. Little waste, though the individual clauses are slightly telegraphic.

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 an output schema (so return values need not be explained) the description covers the action and side effects adequately. The gaps are the undocumented parameters with 0% schema coverage and the absence of explicit alternative-tool routing, which leaves an agent under-informed for a destructive, credit-consuming operation.

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

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

Schema description coverage is 0% across four required parameters (brandId, automationId, revision, idempotencyKey), so the description must compensate and largely does not. 'saved recipe' loosely gestures at automationId and 'the saved automation type must match' hints at matching semantics, but brandId, revision and idempotencyKey are never explained.

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 pairs the verb 'Activate' with a specific resource ('recurring generation using the saved recipe and credit caps') and adds a scope qualifier ('Only social post artwork') that separates it from text-oriented siblings like activate_post_writer_automation. It stops just short of naming an alternative sibling outright, so it is clear but not maximally differentiating.

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

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

'the saved automation type must match this tool' states a prerequisite for calling it, and the delivery sentence hints at what happens after activation. However, there is no explicit when-to-use versus resume_*/pause_*/prepare_* siblings or when-not-to-use guidance, leaving usage largely 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 destructiveHint=true, idempotentHint=true and openWorldHint=true. The description adds useful context beyond them: it consumes 'credit caps' and that approved delivery can 'publish to connected channels', explaining the open-world side effect. It does not spell out irreversibility or what gets destroyed on reactivation, 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?

Three short sentences with the action front-loaded and no filler. The final constraint sentence is dense but earns its place; structure is efficient.

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

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

Output schema exists so return values need not be described, and the activation/publishing behavior is covered. But for a destructive, idempotent mutation with 0% param coverage, the absence of any revision/idempotencyKey guidance leaves a real gap for an agent trying 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 0% across 4 required parameters, so the description carries the full burden — but it explains none of brandId, automationId, revision or idempotencyKey. 'Saved recipe' loosely gestures at automationId, but the versioning (revision) and idempotency semantics are entirely absent.

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 ('Activate') and resource ('recurring generation using the saved recipe'), and the closing clause ('Only vertical story artwork; the saved automation type must match this tool') scopes it away from the many sibling activate_* tools. Clear what the tool does, though the type-matching constraint is the only differentiation and could be crisper.

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 implied prerequisite — the saved automation must already exist and its type must match — plus a note that 'previously approved automatic delivery can publish to connected channels'. However it never names alternatives (resume_/update_/prepare_story_creator_automation) or states when NOT to use this activation 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?

The annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and idempotentHint=true. The description adds valuable behavioral context beyond those annotations: recurring generation, credit-cap consumption, and that previously approved automatic delivery can publish to connected channels.

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

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

The description is three front-loaded sentences with no wasted text. Each sentence adds a distinct piece of information: activation scope, publishing side effect, and type restriction.

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

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

For a destructive, open-world activation tool, the description covers purpose, side effects, and type constraints, and an output schema exists to cover return values. However, with 0% schema description coverage on four required parameters, it leaves a meaningful gap in how to call the tool 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%, and the description does not explain any of the four required parameters (brandId, automationId, revision, idempotencyKey). Terms like 'saved recipe' and 'credit caps' do not map back to the parameters, leaving the agent without parameter 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 uses a specific verb (activate) and resource (recurring generation / UGC storyboard automation) and explicitly distinguishes this tool from sibling automation types with 'Only UGC storyboard frames; the saved automation type must match this tool.' An agent can identify what the tool does and which automation family it belongs to without opening the schema.

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

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

It gives clear context for use: a saved recipe, credit caps, and matching saved automation type. It also includes an exclusion ('Only UGC storyboard frames'), but it does not explicitly compare against alternatives such as prepare, resume, or update automation.

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 idempotentHint=true and destructiveHint=false, so the description only needs to add beyond that. It does: it discloses the cost boundary (no paid scan on save) and the retry contract (reuse idempotencyKey), both operationally important facts not derivable from 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?

Four short, front-loaded sentences covering purpose, prerequisite, cost behavior and retry contract. No filler or redundancy; each sentence adds a distinct actionable 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?

A 6-parameter mutation tool with an output schema, so return format needn't be described. Cost, idempotency and prerequisite are covered; the only real gap is the meaning of brandId/label and duplicate-target behavior.

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

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

Schema description coverage is 0%, so the description must compensate. It explains idempotencyKey's retry semantics and effectively maps the platform parameter values, and the enum self-documents category, but brandId, label and url semantics remain undocumented beyond the tool phrasing.

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

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

States a specific verb (save) and resource (target), and enumerates the accepted platform types (YouTube, X, website, RSS) matching the platform enum. It implicitly separates itself from scan_intelligence_target by clarifying that saving does not start a scan, though it never names that sibling outright.

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?

'Check capabilities first' is explicit prerequisite guidance pointing at get_intelligence_capabilities, and 'Saving does not start a paid scan' tells the agent when NOT to expect a scan (i.e., use scan_intelligence_target for that). No explicit exclusion list, but the context is clear enough to choose correctly.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the agent knows this mutates state and is not idempotent. The description adds two useful behavioral facts: it consumes an analysis allowance and returns a creative hypothesis rather than proof of profitability. It does not explain why the operation is non-idempotent or how retries with the idempotencyKey behave.

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

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

Two short sentences front-load the action and immediately qualify the output. There is no filler, though the description is arguably too terse for a tool with three required parameters and a non-idempotent mutation annotation.

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?

An output schema exists, so return values need not be described, and the caveat about hypotheses is a useful addition. But for a non-idempotent, open-world analysis call with three fully undocumented required parameters, the description omits parameter meaning, allowance limits, and sibling differentiation, leaving it 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?

Schema description coverage is 0% and the description never mentions adId, brandId, or idempotencyKey. An agent must infer that the 'selected public ad' corresponds to adId and that brandId scopes the analysis. Required argument meaning and the idempotency contract are undocumented in both description and schema.

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

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

The description states a specific verb (Analyze) and resource (a selected public ad), which is clearer than the name alone. However, it does not distinguish this tool from nearby siblings like get_library_ad, get_ad_breakdown, or compare_intelligence, which an agent must choose between when working with library ads.

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 guidance on when to use this tool versus alternatives such as get_library_ad, search_library_ads, or get_ad_breakdown. The mention of an 'existing analysis allowance' hints at a precondition but does not state when to choose this tool or what happens when the allowance is exhausted.

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 idempotentHint=true, destructiveHint=true, and readOnlyHint=false; the description adds genuinely useful context beyond them ('App-only' auth posture and the scope limit 'does not activate or publish'). It does not explain why the operation carries destructiveHint=true (e.g., whether approving one revision invalidates others) or what state changes result, leaving the destructive profile opaque.

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, front-loaded sentences with no filler; the scope clarifier follows immediately after the purpose. However, for a five-parameter destructive mutation the brevity edges into under-specification rather than tight conciseness.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. But with no parameter descriptions and a destructive, idempotent write, the description omits prerequisites (must match the reviewed revision), idempotency behavior, and the consequence of approval, leaving real gaps for an agent to act on.

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

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

Schema description coverage is 0% across five required parameters, so the description carries the full burden. It only implicitly touches automationId/revision ('automation revision') and sampleRunId ('sample'), leaving brandId, the revision-vs-sampleRunId relationship, and idempotencyKey semantics entirely unexplained, including the practical need to match the revision the sample was generated against.

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 (approve) and resource (completed sample and automation revision), with the qualifier 'exact ... reviewed in the UI' pinning down which sample. It also distinguishes itself from the activate_* sibling family by stating 'does not activate or publish'. It stops short of naming which sibling produces the sample or what activation follows, but the purpose is clear.

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

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

The phrase 'reviewed in the UI' implies the prerequisite workflow (generate/prepare a sample, inspect it, then approve), and 'App-only' signals who may call it. However, against a sibling list containing generate_*_automation_sample, prepare_*_automation, and activate_*_automation, it never explicitly states the when-to-use condition or the downstream alternative, so routing relies on 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=false, destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety and repeat-call profile is covered structurally. The description adds that approval is bound to one exact revision and that the tool is UI-gated, but says nothing about what an approval replaces or whether prior approvals are superseded.

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

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

Two short sentences with zero filler; the action and its scope come first and the access restriction second. Nothing needs trimming or reordering.

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?

An output schema exists, so return values need not be described, and annotations cover safety. Still, for a destructive, idempotent write with four undocumented parameters, the description omits prerequisites, the effect of approval on existing facts, and how to source the four IDs.

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 carries the full burden, yet it only gestures at 'revision' (implying an exact-match/optimistic-concurrency value). brandId, factId and especially idempotencyKey are left entirely unexplained in both schema and description.

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

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

States a specific verb (Approve) and resource (a business fact revision), and the qualifier 'the exact ... revision reviewed in the card' narrows the target beyond a generic fact. It is distinguishable from list_brand_facts and save_brand_fact, though 'the card' is UI jargon an agent may not resolve.

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?

'Only available to the app UI' is an explicit, actionable when-not-to-use constraint that prevents an agent from calling it. However, it names no alternative tool (e.g. save_brand_fact) and does not state the prerequisite that a revision must have been reviewed/saved first.

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=true and readOnlyHint=false, so safety is covered structurally. The description adds real context on top: approval is bound to one exact snapshot (not a live/editable campaign), it cannot trigger scheduling or publishing, and it is UI-only — all useful behavioral facts not derivable from 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?

Two sentences, zero filler, with the core action and scope front-loaded before the constraints. Every clause earns its place by either defining what is approved or carving out what it does not do.

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?

An output schema exists so return values need no explanation, and annotations cover the mutation profile. However, for a destructive, snapshot-bound mutation with 4 fully undocumented parameters, the description leaves the parameter contract and any permission prerequisites underspecified.

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 4 required parameters, so the description must carry the load. It explains the concept behind `snapshot` (the exact reviewed campaign snapshot), but brandId, campaignId and idempotencyKey get no mention — an agent must infer their roles entirely, and the snapshot format/hash binding is left unexplained.

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

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

States a specific verb (Approve) and resource (campaign snapshot), and pins the scope precisely: 'content, settings, assets, facts and times'. The explicit 'Does not schedule or publish' cleanly separates it from schedule_campaign and prepare_campaign, which an agent could otherwise confuse it with from the name alone.

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

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

Gives clear context and boundaries: approval is the terminal action on an already-reviewed snapshot, and it does not schedule or publish, implicitly routing to schedule_campaign for that step. It also states a hard availability constraint ('Only available to the app UI'). It stops short of explicitly naming the alternative tool or the precondition that a review card must exist first.

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=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine value beyond that: it discloses that the recipe will not run and that in-flight work may still complete — non-obvious side-effect timing an agent needs.

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 two scoping caveats. No filler, no repetition of the tool name.

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

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

Annotations and the existing output schema relieve the description of explaining safety and return values, and the archival side-effects are noted. However, for a destructive mutation with four required parameters at 0% schema coverage, the absence of any parameter or concurrency guidance leaves an agent under-informed on how 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 0% and the description says nothing about the four required parameters. Names like brandId and automationId are largely self-explanatory, but revision (optimistic concurrency) and idempotencyKey carry non-obvious semantics that go undocumented anywhere, so the description fails to compensate.

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: 'Archive a saved automation.' That is clear on its own, and it distinguishes the operation from executing the recipe. It does not explicitly contrast with close siblings like pause_automation or delete-type operations, so it falls just 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?

The description clarifies scope ('Does not execute its recipe') but never says when to archive versus pause_automation, resume_* or other lifecycle operations. Usage is implied by the verb 'archive' rather than stated, and there are no exclusions or alternative-routing hints.

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=true; the description adds meaningful scope beyond them by bounding the destruction (editable-only) and stating the refusal conditions. Wording like 'uncertain delivery' is imprecise, keeping it from a 5.

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

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

Two sentences with the action stated first and the guardrail second; every clause carries information. Slightly awkward phrasing but no filler.

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

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

An output schema exists, so return values need no explanation, and the annotations plus description cover the safety profile. However, with 0% param documentation and no explanation of the idempotency contract, an agent still lacks enough to invoke 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?

Schema description coverage is 0% across three required params. The description only incidentally echoes 'revision' via 'post revision' and says nothing about postId or idempotencyKey semantics, 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 ('cancel') and resource ('the expected post revision'), which separates it from cancel_research and the delete_* siblings. The qualifier 'expected' is vague, but the core action is identifiable.

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

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

Gives an explicit precondition ('only while safely editable') and an explicit exclusion ('never cancels a post already publishing or with uncertain delivery'). It doesn't name sibling alternatives, so it falls short of a 5.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, readOnlyHint=false), the description adds real behavioral value: work already performed still incurs credits and final usage/refunds only appear after settlement. This is exactly the kind of cost/settlement context annotations cannot convey, though it omits auth or timing details.

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

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

Two tight sentences with zero waste and the consequence front-loaded after the action. Only minor weakness is that the opening sentence is thin relative to the useful second 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?

An output schema exists so return values need not be explained, and the key concern for a cancellation tool — cost/refund implications — is covered. However, with three undocumented required parameters and no usage context, it is only minimally complete for a destructive, idempotent-keyed operation.

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

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

Schema description coverage is 0% across three required parameters (brandId, runId, idempotencyKey) and the description supplies no meaning for any of them. Notably idempotencyKey is never mentioned even though the annotation flags idempotency, so the description 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?

The sentence 'Request cancellation' essentially restates the tool name without naming the resource being cancelled (a research run) or distinguishing it from near siblings like cancel_post or pause_research_schedule. An agent gets the action but not the object or the boundary against similar 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?

No when-to-use guidance is given and no alternative is named. The credits/refund note hints at a caution, but there is no explicit condition telling the agent when to cancel versus pause a schedule or when not to cancel 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?

Annotations already declare this a safe, idempotent, non-destructive read, so the bar is lower. The description nevertheless adds genuinely useful behavioral context: results are bounded by differing observation times and missing metrics, warning the agent that conclusions are approximate rather than authoritative.

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

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

Two sentences, zero filler. The operation and its subject come first, and the reliability caveat is placed after the action rather than padding the opening.

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?

Safety is covered by annotations and return shape by the output schema, so those gaps don't count. What is missing is the practical context an agent needs to call it correctly: that targets must be saved intelligence targets for that brand and that metrics must have been observed first.

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 carries the burden, and it does partially: it clarifies that targetIds are tracked sources belonging to the given brand and that the count is two or three. It still says nothing about the brandId/targetId formats or the brand-to-target ownership requirement beyond a bare implication.

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: comparing saved public metrics across two or three tracked sources for a brand. That is enough for an agent to understand the operation, though it never names or distinguishes itself from siblings like get_intelligence_target or scan_intelligence_target.

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

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

There is no when-to-use guidance, no prerequisites (targets must already be tracked/saved and presumably scanned), and no routing to alternatives such as fetching a single target's metrics. The 'two or three sources' constraint is restated from the schema rather than offered as selection 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 a non-read-only, idempotent, open-world, non-destructive operation, so the bar is lower; the description still adds real value with the consent-flow disclosure and the credential caution ('never request passwords or bot tokens'). It also converts idempotentHint into an action ('Reuse the idempotency key'). It does not cover auth prerequisites beyond 'authorized brand' or rate 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?

Four short sentences, front-loaded with the core action before drilling into platform branches, security, and idempotency. Every sentence carries information; no filler or restatement of the name.

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

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

For a multi-platform OAuth-style connection tool with an output schema present (so return values need not be described), the description covers the initiation, platform-specific branches, consent, and credential safety. Minor gaps remain around post-consent completion/polling and brand authorization requirements.

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 carry the load; it does semantically map three params (server for Mastodon, platform as 'one social platform', idempotencyKey for reuse). However, it says nothing about brandId beyond 'authorized brand', nor about platform enum values or key format, leaving genuine gaps at 0% coverage.

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

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

States a specific verb and resource ('Start connecting one social platform to an authorized brand'), so an agent knows this initiates a channel-connection flow rather than reporting on one. It does not name or differentiate itself from siblings like get_channel_connection or select_channel_accounts, so it falls short of a 5 on distinction.

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

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

Provides concrete invocation context via per-platform branches ('For Mastodon, provide the user's server'; Telegram's bot selection + confirm step), which clearly signals when and how this flow applies. It stops short of explicitly stating when to prefer this over list_connected_accounts/get_channel_connection or the ordering relative to select_channel_accounts.

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

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

Annotations already declare the write/idempotent/open-world safety profile, and the description adds real context beyond them: plan-limit gating, that refresh cadence is driven by existing platform jobs with no custom schedule promised, and idempotency-key reuse guidance. These are meaningful behavioral traits not present in 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?

Three short sentences, purpose front-loaded, no filler. Each sentence carries distinct information, though "Reuse idempotencyKey" is terse enough to need inference about why reuse matters.

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?

An output schema exists so return values need not be described, and the mutation's cadence/limit behavior is covered. However, with 5 undocumented required parameters and no link to search_advertisers for obtaining the advertiser, the definition is only adequate for a creation tool.

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

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

Schema description coverage is 0% across 5 required params, so the description must carry the load. It clarifies that advertiserId/advertiserName must reference a previously selected public advertiser and explains idempotencyKey reuse, but says nothing about the source enum (meta/tiktok) or format expectations for the other fields.

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

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

States a specific verb+resource ("Create a watch") scoped to "a selected public advertiser" within a brand's plan. The verb alone distinguishes it from delete_ad_watch, get_ad_watch and list_ad_watches, so no explicit sibling naming is needed. 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?

It gives a precondition ("within this brand's existing plan limits") and implies the advertiser must already be selected, but never says when to use this versus list_ad_watches/get_ad_watch or how to obtain a valid advertiser. 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 non-destructive, idempotent, closed-world. The description adds genuine value beyond them: 'Use existing media IDs' (no upload path), 'Does not publish or schedule' (write but not live), and 'Reuse idempotencyKey on retry' (how to leverage idempotency). It omits auth/permission needs and error behavior.

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

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

Four short sentences, zero filler, and the key facts (save draft, platform fallback, no publish, retry with same key) are front-loaded. 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?

The output schema means return values need no explanation, and the description covers the non-publishing semantics well. However, for a tool with a deep nested settings object at 0% schema coverage, the description gives an agent no guidance on which settings apply to which platform, leaving a meaningful gap.

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

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

Schema description coverage is 0%, so the description must compensate. It gestures at idempotencyKey, media IDs, platform, and connected account, but explains nothing about brandId, content, or the large nested settings object (30+ platform-specific fields). Partial compensation only.

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 ('save a reviewable draft') and immediately carves out scope with 'Does not publish or schedule,' which cleanly separates it from siblings like schedule_post and cancel_post. An agent can tell exactly what this tool produces.

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 two concrete usage modes (connected account vs. draft-before-connecting by supplying platform) and an explicit exclusion ('Does not publish or schedule'). It stops short of naming the alternative sibling tools to call for publishing/scheduling, so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the operation is a metadata save with no downstream publishing/scheduling, and results are observational so causal claims are unsupported. It does not disclose duplicate-handling or idempotencyKey behavior, but the annotations cover idempotency.

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

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

Three short sentences, front-loaded with the action and payload, with the two constraints following. Every sentence carries information, though the closing causal-attribution sentence is more of an interpretive directive than a description of the tool's own behavior.

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

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

The output schema exists, so return values need no explanation, and annotations cover the safety profile. However, for a 6-required-parameter mutation at 0% schema coverage, the description leaves idempotencyKey, brandId scoping and minimumPostsPerVariant unexplained, which is a real gap for correct invocation.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the load and it only partially does. It names hypothesis, metric and 'labeled post variants' (hinting at the label/postIds structure), but brandId, idempotencyKey and minimumPostsPerVariant are left completely undocumented in both schema and prose.

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

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

The description gives a specific verb+resource ('Save ... an observational content experiment') and enumerates the core payload (hypothesis, success metric, labeled post variants), which lets an agent distinguish it from get_experiment and list_experiments. It stops short of explicitly naming those siblings, so it is clear but not fully 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?

'Does not publish or schedule' explicitly carves out the boundary against the many schedule_*/publish-adjacent siblings, and the causal-attribution caveat sets expectations for use. It never names an alternative tool or states a positive when-to-use condition, so it falls short of full routing guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds a concrete retry instruction (reuse the idempotencyKey), which is useful, but it does not disclose what is destroyed, whether removal is reversible, or any auth requirements.

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

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

Two short sentences with zero filler; the destructive action is front-loaded and the retry caveat follows immediately. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and annotations carry the destructive/idempotent safety profile. Still, for a destructive delete the description leaves consequences and scope unstated, and it does not compensate for the 0% parameter coverage.

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 all three parameters are required, so the description carries the full documentation burden. It explains idempotencyKey usage on retry, but offers no meaning at all for brandId or watchId, leaving two of three parameters 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?

States a specific verb ('Remove') plus resource ('advertiser watch') and scope ('this brand's selected'), which cleanly distinguishes it from create_ad_watch, get_ad_watch and list_ad_watches. It does not, however, name an explicit alternative the way a 5-level description would.

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 delete a watch versus creating or fetching one, nor any prerequisites or exclusions. The only usage instruction ('Reuse idempotencyKey on retry') concerns retry mechanics rather than tool selection, so an agent gets little help deciding when this tool is appropriate.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a concrete retry rule, but omits whether deletion is permanent/recoverable and what happens if itemId is unknown – gaps that matter 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?

Two short sentences, front-loaded with the action and scope, with the retry hint last. Nothing wasted.

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

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

An output schema exists so return values needn't be explained, but for a destructive, 3-required-param tool with 0% schema descriptions the definition should at least state whether the deletion is irreversible and what the itemId refers to beyond 'the item the user selected'.

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 carry the load. It only clarifies idempotencyKey semantics; brandId and itemId are partially inferable from the prose ('the specific saved evidence item ... from this brand') but no format or failure semantics are given.

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 ('Delete the specific saved evidence item') and scopes it to a brand. This distinguishes it reasonably from delete_intelligence_target and delete_saved_ad, 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 only guidance is retry behavior ('Reuse idempotencyKey on retry'), which is lifecycle advice rather than selection advice. There is no statement of when to use this instead of delete_intelligence_target or delete_saved_ad, nor any precondition or exclusion.

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=true, and readOnlyHint=false. The description adds user-request gating and idempotency-key reuse guidance, which are useful, but does not clarify what removal actually destroys (e.g., whether scan history is lost) or any permission requirements.

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

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

Two tightly written sentences with zero waste. The purpose is front-loaded and the retry hint follows naturally, with no redundant restatement of schema or annotations.

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 tool, annotations and an output schema cover safety and return-value explanation, and the description supplies the user-request precondition and retry behavior. However, it leaves unresolved what 'remove' means operationally and says nothing about the identity/format of the two ID parameters.

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 three required parameters. The description gives meaning only for idempotencyKey ('Reuse idempotencyKey on retry'), leaving brandId and targetId entirely undocumented in both schema descriptions and prose beyond their 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?

States a specific verb (Remove) and resource (the selected tracked public source) scoped to a brand. This distinguishes it from get/list/add/scan siblings, though it does not explicitly name an alternative tool and uses 'tracked public source' rather than the tool name's 'intelligence target', requiring mild inference.

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

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

Provides a clear when condition: deletion should happen 'after the user requests removal', implicitly warning against proactive deletion. It adds an operational retry guideline ('Reuse idempotencyKey on retry') but names no explicit alternatives or when-not-to-use 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds only "Reuse idempotencyKey," which restates the retry-safety idea; it says nothing about permanence, cascading effects, or whether the brand's collection is affected beyond the one item.

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, purpose front-loaded, no filler. Every clause contributes; the idempotency note is placed second where it belongs.

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?

An output schema exists so return values need not be described, and annotations cover the mutation profile. However, with all three parameters undocumented in the schema, the definition is thin for a destructive operation whose inputs an agent must construct 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%, so the description carries the full burden for three required parameters. It only loosely implies brandId ("this brand's") and savedId ("a specific saved ad"), and gives no meaning for the UUID format or the idempotencyKey pattern beyond a vague reuse instruction.

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

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

States a specific verb ("Remove") and resource ("a specific saved ad") scoped to "this brand's inspiration collection," which is enough to distinguish it from list_saved_ads and save_library_ad. It does not explicitly name any sibling tool, 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 statement of when to use this versus alternatives like delete_intelligence_saved or when not to delete. "Reuse idempotencyKey" is a retry hint, not selection guidance, so the agent is left to infer the use case entirely.

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 openWorldHint=true, readOnlyHint=false, idempotentHint=false and destructiveHint=false. The description adds genuinely useful context beyond them: the suggestions are proposals that are not persisted. It does not say whether the discovery runs synchronously, what it costs, or what state (if any) the required flowId changes.

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, front-loaded sentences with no filler; the key action leads and the non-persistence caveat follows. It is efficient, though the terseness leaves little room for the missing parameter guidance.

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

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

An output schema exists, so return values need not be described. But with four undocumented required parameters and an unstated discovery/async model, an agent still lacks the input-side information needed to call this 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 carry the burden for four required parameters. It only loosely implies 'website' (brand website) and 'flowId' (existing discovery); 'brandId' and 'name' are never addressed, and no formats or constraints are restated.

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: it reads the brand website to propose brand profile suggestions. The clause 'Does not save them' implicitly distinguishes it from update_brand_profile, though that sibling is never named explicitly.

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

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

'Using existing discovery' hints at a prerequisite (an existing discovery flow, matching the required flowId), and 'Does not save them' clarifies the non-persisting outcome. However, it never states when to choose this over update_brand_profile or get_brand_context, so usage is only implied.

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

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

Annotations already declare non-destructive, open-world, idempotent behavior, so the bar is lower, and the description still adds genuinely new context: the operation consumes credit caps, it does not publish, and the saved automation must be the matching type. It omits idempotency/retry semantics despite the idempotencyKey parameter, so it is not exhaustive.

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

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

Three short sentences, front-loaded with the action and outcome, with no filler. The final clause is slightly terse/ambiguous but still earns its place by encoding a hard 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, for a four-required-parameter mutation in a 20-plus sibling family, the description leaves parameter meaning and sibling routing gaps that 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?

Schema description coverage is 0% across all four parameters, so the description carries the full burden and largely fails: brandId, revision, and idempotencyKey are never explained. Only an oblique hint exists that automationId must reference a saved automation of the matching type.

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

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

States a specific verb and resource ('Generate a paid review sample using the saved recipe') and scopes it ('Only advertising artwork'), which separates it from the surrounding non-sample siblings. It does not name the rescue path relative to prepare_/activate_/resume_ variants of the same family, so sibling differentiation is only partial.

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

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

Gives one real precondition ('the saved automation type must match this tool') and clarifies the outcome ('Does not publish'), which implies this is a preview/review step. It never states when to call this instead of prepare_ad_creative_builder_automation or activate_ad_creative_builder_automation, so the workflow position 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?

Adds meaningful context beyond the annotations: this is a paid operation consuming credits ('its credit caps'), and it explicitly does not publish. These complement the annotation profile (readOnlyHint=false, idempotentHint=true) without contradicting it, though it omits what gets produced or how failures/credits behave.

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

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

Three short, front-loaded sentences with no filler; the core action leads and constraints follow. The fragment 'Only images with backgrounds removed' is slightly terse but still clear.

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?

An output schema exists so return values need not be described, and the non-publish/credit behavior is covered. But with 4 required params at 0% schema coverage and no explanation of revision or idempotencyKey, the description leaves a meaningful gap for a paid, idempotency-keyed generation call.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only indirectly references automationId ('saved recipe,' 'automation type must match'). brandId, revision, and especially idempotencyKey (which underpins the idempotentHint) are left unexplained, leaving the agent to infer their 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 ('Generate a paid review sample using the saved recipe') and scopes it to this automation type via 'the saved automation type must match this tool,' which separates it from the ~20 same-shaped generate_*_automation_sample siblings. It does not name a sibling tool outright, so it falls just short of 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?

Gives preconditions ('only images with backgrounds removed,' automation type must match) and clarifies 'Does not publish,' implying a later approval step. However, it never names the alternative tools (prepare_background_removal_automation, approve_automation_sample) or states when to pick this over them, so usage is only implied.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds context annotations cannot express: generation 'does not publish' and draws against the recipe's credit caps. That credit-consumption and non-publishing disclosure is meaningful for a tool the annotations flag as a non-read-only action. It stops short of stating auth/permission requirements.

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

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

Three short sentences, each doing distinct work: what is produced and its credit basis, what it deliberately does not do (publish), and the scope/type-match constraint. Front-loaded and free of padding.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. But for a 4-parameter, 0%-coverage operation the description omits all parameter meaning and any relationship to the sibling prepare/approve/activate tools it is clearly part of, leaving the agent to reconstruct the workflow.

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 carries the full burden, yet it names none of the four required parameters. The only implicit semantics supplied is for automationId (it must reference the matching banner automation type). brandId, revision, and idempotencyKey — including the retry/idempotency contract implied by that last one — remain completely undocumented.

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 object ('Generate a paid review sample') and scopes itself against the ~19-strong family of sibling generate_*_automation_sample tools by declaring 'Only banner artwork'. The phrase 'paid review sample' is mildly non-standard jargon, but combined with 'using the saved recipe' an agent can identify the action and its narrow domain without opening the schema.

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

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

The description supplies a real precondition — the saved automation type must match this tool — which implicitly routes the agent away from the campaign/image/logo variants. However it never states when to call this versus prepare_banner_generator_automation, approve_automation_sample, or activate_banner_generator_automation, so the agent must infer the position in the generate→approve→activate workflow.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, covering the safety profile. The description usefully adds that no publish occurs and that output is limited to written campaign sections. It does not, however, explain what the credit caps do, what a non-match failure looks like, or what happens to the existing sample on regeneration.

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

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

Three short sentences with no filler, and the core action is front-loaded before the two constraint clauses. Efficient, though slightly telegraphic in the second clause.

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

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

An output schema exists so return values needn't be described, but with four required, fully undocumented parameters and only annotations for behavioral guidance, the definition leaves an agent without enough to invoke it correctly — especially the meaning of revision and the automation-type matching requirement.

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 all 4 parameters, so the burden falls on the description, which provides essentially no parameter meaning. Terms like 'saved recipe', 'revision', 'automationId' and 'credit caps' are mentioned in passing but never tied to the actual inputs, leaving revision, brandId and idempotencyKey unexplained.

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

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

States a specific verb (Generate) and resource (paid review sample via saved recipe and credit caps), and the clause 'Only written campaign sections' distinguishes it from the many image-oriented generate_*_automation_sample siblings. It is clear what the tool does, though it never names an alternative by 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 two useful constraints: 'Does not publish' (a when-not boundary) and 'the saved automation type must match this tool' (a precondition). However, it does not direct the agent to the relevant siblings (prepare_campaign_generator_automation, approve_automation_sample, or the other generate_*_automation_sample tools) or say when this sample generation step is appropriate in the workflow.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: it consumes credits against 'credit caps', it produces a sample without publishing, and it requires a matching saved automation type. That is meaningful disclosure 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?

Three short sentences, front-loaded with the action and immediately followed by the two constraints. No filler or restated field names.

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?

An output schema exists, so return values need not be explained, and the mutation's non-publishing nature and type-match requirement are stated. The remaining gap is that the four required inputs are neither described nor illustrated, leaving an agent to infer how to construct a valid call.

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

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

Schema description coverage is 0% and all four required parameters (brandId, automationId, revision, idempotencyKey) are undocumented. The description alludes to 'the saved recipe' and the matching automation type, which loosely gestures at automationId, but it explains nothing about brandId, revision, or idempotencyKey, 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 ('Generate a paid review sample') and narrows scope with 'Only captions and hashtags', which distinguishes it from the other generate_*_automation_sample siblings. It does not name a sibling explicitly, so it lands 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?

Gives a real precondition ('the saved automation type must match this tool') and a negative constraint ('Does not publish'), which is useful context. However, it never explains when to choose this over the prepare_/activate_/resume_ variants of the same automation, so routing 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?

The annotations already declare idempotentHint=true and destructiveHint=false, so safety is largely covered. The description still adds real value: it consumes credit caps, it explicitly does not publish, and it requires the saved automation type to match — none of which the annotations convey.

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

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

Three terse, front-loaded sentences with essentially no filler; the core action and the key non-publication constraint come first. Slightly clipped in places, but every sentence carries 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?

An output schema exists (so return values need not be described) and annotations cover the safety profile, so the description is not obligated to restate those. Still, for a required-parameter write operation embedded in a large sibling family, the absence of parameter semantics and workflow routing leaves meaningful gaps.

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

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

Schema description coverage is 0% and all four parameters (brandId, automationId, revision, idempotencyKey) are required, yet the description mentions none of them. 'The saved recipe' loosely gestures at automationId but provides no format, role, or constraint detail, 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?

The description states a specific verb (Generate) and resource (a 'paid review sample' for the carousel creator automation), which is clearer than most of the family. However, it never explicitly distinguishes itself from the many sibling variants (prepare_*, activate_*, resume_*, update_*), leaving the agent to infer the workflow position from the name alone.

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

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

The constraints 'Does not publish' and 'the saved automation type must match this tool' imply when it applies, but there is no explicit when-to-use guidance and no routing against prepare_carousel_creator_automation or activate_carousel_creator_automation. Usage is implied rather than stated.

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

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

Annotations declare write/idempotent/non-destructive/open-world, and the description adds genuinely new context: the sample is 'paid' (consumes credits bounded by credit caps) and 'Does not publish' (creates a review artifact rather than a live post). That billing and no-publish behavior is not in the annotations and is valuable. It could go further on what the sample 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 tightly packed sentences with the core action front-loaded and constraints following. No filler. The phrase 'Only edited source images' is slightly cryptic but overall efficient.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. Still, for a four-required-parameter tool with 0% schema coverage, the description omits parameter meaning and preconditions (e.g., a prepared recipe existing), leaving gaps an agent must fill 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% across four required parameters (brandId, automationId, revision, idempotencyKey). The description loosely implies a saved recipe (automationId/revision) but never explains revision semantics, the idempotencyKey, or brandId. With zero schema documentation this leaves the caller to infer 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+resource (generate an edit-image automation sample) and clarifies it operates on the saved recipe with its credit caps. The clause 'the saved automation type must match this tool' implicitly differentiates it from the many sibling generate_*_automation_sample tools. It stops short of naming an alternative, but the purpose is clear.

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

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

Gives some routing context: it must match the saved automation type, and it does not publish. However it never names the alternatives (e.g., prepare_edit_image_automation or the other generate_*_automation_sample siblings) nor states prerequisites such as needing a saved recipe first. 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.