Soclo

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

Annotations already declare destructive/idempotent/openWorld, and the description adds real context beyond them: the manage:accounts permission requirement, the confirm-gated preview that changes nothing, the fact that existing profiles are reused, and that an interrupted run leaves an unconfirmed state. That is substantive behavioral disclosure, with no contradiction of 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 dense sentences, front-loaded with purpose and scoping before prerequisites and recovery. Nearly every clause carries distinct information, though the recovery/reuse material could be marginally tighter.

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 rich annotations, 100% schema coverage, and an output schema, the description does not need to explain return values. It covers the remaining gaps an agent needs: permissions, preview gating, reuse of existing profiles, and interrupted-setup recovery.

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

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

Schema coverage is 100% and both name and confirm are already documented in the schema, including the preview behavior. The description mostly restates the confirm semantics and adds only the "owner-approved" nuance, so baseline 3 is appropriate.

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

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

States a specific verb+resource ("Set up the first social profile") and pins the scope with "first" and "owner-bound profile route," which distinguishes it from sibling tools like soclo_accounts_connect. An agent can tell what this does without opening the schema.

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

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

Gives prerequisites (requires manage:accounts), the condition that selects preview vs write (confirm: true or nothing changes), and explicitly routes recovery to the sibling soclo_accounts_list. When-to-use, when-not, and the alternative are all present.

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

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

Annotations only supply readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false; the description adds real context beyond that: it needs only read:accounts, is free, and involves a human-in-the-loop browser sign-in rather than an API-side action. It also documents the Snapchat flow semantics (no silent API post, no Snapchat ads product in Soclo) and a specific error code. It does not address link lifecycle (expiry/single-use), which matters given idempotentHint=false.

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

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

Purpose, permissions and the X Ads note are front-loaded, which is good, but the Snapchat paragraph is bloated and partly tangential — it explains how personal Snap sharing works through the app editor and repeats the 'never a silent API post' point twice. Several sentences could be cut without losing invocation-relevant 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-value explanation is rightly omitted, and the description covers the platform-specific edge cases that would otherwise trip an agent (X Ads accountId, Snapchat profile selection, no_aggregator_profile recovery). Coverage of the other listed platforms (instagram, facebook, tiktok, etc.) is left to the implicit default flow, which is a minor gap.

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

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

Schema description coverage is 100%, so both platform and accountId are already documented in the schema. The description adds the X Ads-specific meaning of accountId (owned X posting account), which mirrors the schema text, but supplies no extra syntax or format detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The first sentence states a specific verb+resource+outcome: it returns the real Soclo connect link for a named platform, which the owner opens in a browser to sign in. It is clearly distinguishable from soclo_accounts_list (enumerate existing accounts), soclo_accounts_disconnect (remove one), and soclo_accounts_bootstrap (referenced only as an error-recovery step).

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 real routing guidance: pass accountId for X Ads, use the owned X posting account from soclo_accounts_list, and run soclo_accounts_bootstrap first if the call returns no_aggregator_profile. It stops short of an explicit 'use this when you want to add a new account, not to inspect or refresh existing ones' statement, so the when-not condition 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 destructiveHint=true and idempotentHint=true, but the description adds real context beyond them: posting to the platform halts until reconnect, the action cannot be undone from here, and the confirm flag gates a dry-run preview. This materially changes how an agent should 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?

The most important consequence (posting stops) is front-loaded, followed by the safety gate, prerequisites, and ID source. Every sentence carries a distinct operational fact with 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?

With an output schema present, return values need not be explained, and the description covers destructive consequence, consent gating, permission requirement, and parameter provenance. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters are already documented, so the baseline is 3. The description adds meaning on the confirm gating contract (owner consent before true) and points to soclo_accounts_list for accountId, going slightly beyond the schema.

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

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

States a specific verb and resource ('Remove a connected account') and immediately names the substantive consequence (posting stops). It is clearly distinguished from siblings like soclo_accounts_connect and soclo_accounts_list.

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

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

Gives explicit invocation conditions: pass confirm:true only after the owner agreed, otherwise a preview is returned that disconnects nothing. It also names the required manage:accounts permission and the source for accountId (soclo_accounts_list), leaving nothing to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely useful context: the auth scope needed, that the call is free, and the important caveat that status is always "connected" with no expired/needs-reauthorisation states. 'Changes nothing' mostly restates destructiveHint=false, keeping 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?

Two sentences, front-loaded with what is returned and only then the caveats. The parenthetical about finer-grained status is slightly verbose but earns its place by preventing a wrong assumption about the status field.

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

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

With no output schema, the description correctly takes on the burden of explaining return values and does so. Annotations cover the safety profile and there are no parameters, so nothing critical is missing; only an explicit alternative-tool pointer would improve it.

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

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

There are zero parameters, so the baseline is 4. The description still adds value by naming the fields the listing surfaces (platform, handle, status), which helps the caller interpret the result despite the absence of an output 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 names a specific verb (list) and resource (every social account connected to this Soclo account) and even enumerates the returned fields (platform, handle, status). It is easy to separate from the accounts siblings bootstrap/connect/disconnect, which mutate connection state.

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 by stating the required scope (read:accounts) and clarifying that ad-only connections are included, but it never says when to reach for this versus soclo_accounts_bootstrap or other account-state tools, nor does it state any exclusions. Usage is implied rather than guided.

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 idempotent=true and destructive=false, and the description adds substantial context beyond that: the switch changes the target of every later Soclo tool on the connection (credits, Brand Kit, library, posts, connected accounts), and paid actions then spend the client's own credits while still going through quote and approval. That is exactly the kind of side-effect disclosure an agent needs before mutating session state.

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 audience qualifier and the primary mode come first, and every sentence carries a distinct instruction. The enumeration of affected resources is slightly verbose but does real work by conveying the blast radius of the switch.

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 single optional parameter and no output schema, the definition covers discovery mode, switch semantics, revert behavior, and the safety check before spending. Nothing an agent needs to call this correctly is absent.

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

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

Schema coverage is 100%, so the enum values and format are already documented. The description still earns credit by naming the source of valid IDs (an accountId from the list) and by describing what each value does downstream, not just what it is.

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 action (switch the account context) and its three modes: no-arg listing, accountId switching, and "self" returning to the agency's own account. It is clear what the tool does, though it doesn't explicitly contrast itself with the sibling soclo_accounts_list, which also lists accounts and creates a plausible ambiguity.

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 concrete when-to-use guidance (call with no accountId to discover accounts, call with a listed accountId to switch, pass "self" to revert) and adds an operational caution about announcing the active business before paid or publishing actions. What's missing is an explicit warning not to use soclo_accounts_list for this purpose.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds substantive context on top: credit spend, mandatory owner price approval, active account rights for imports, and the image-specific fictional rights declaration requirement. The rights/compliance guardrails ('do not invent owner words', 'use Soclo's verified-person flow for real people') are behavioral facts an agent could not infer from annotations or schema.

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

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

The pricing/approval prerequisite is front-loaded and every sentence carries actionable content, with no filler. It is dense and somewhat run-on for a single paragraph, packing pricing, origin, rights, and replay guidance together, so a reader must parse carefully to extract the ordered call sequence.

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, credit-spending tool with 10 undocumented parameters and no output schema, this covers what matters most: cost, approval, rights attestation, mode selection, and idempotent replay handling. Remaining gaps are what a successful creation returns (actor id?) and what failure modes exist (insufficient credits, offer mismatch), which would help but are secondary to the guidance given.

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 0% schema description coverage across 10 parameters, the description carries heavy load and does so well: it explains origin's enum values, assetId/assetVersion as a current owned Brand Kit asset, expectedCredits/pricingVersion as coming from the offer, ownerApprovedPrice as an owner-facing gate, ownerRightsDeclaration's scope and the narrow case for omitting it, and clientRequestId as a stable replay key. The one gap is `spec` — its content and 400-character intent are never described, so an agent must guess what belongs there.

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 up front ('creates one reusable fictional character from name and spec') plus the cost consequence ('Spends credits'). It further disambiguates the two creation modes (soclo_generated vs owner_imported), which no sibling tool covers, so an agent can separate this from soclo_actors_list/select/remove without opening a schema.

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

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

Gives explicit when-to-use routing: read soclo_actors_list for the live offer, show it to the owner, then pass ownerApprovedPrice:true with the offer's exact expectedCredits and pricingVersion. It also names the condition that selects each origin mode and prescribes the recovery path (reconcile with soclo_actors_list rather than starting another purchase) when an outcome is uncertain.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description still adds the cost/free framing and, more importantly, the null selectionVersion semantics as a legitimate first-selection claim. That is genuine behavioral context beyond the structured fields. It does not say what happens when no actor has ever been selected (error vs null), which is the remaining gap.

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

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

Three short sentences, front-loaded with what is read, then the cost posture, then the one non-obvious edge case. Nothing is padded and no sentence repeats the title or schema.

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

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

For a zero-parameter read with no output schema, the description covers what is returned (star plus selectionVersion) and how to handle a null version. The only missing piece an agent might need is the behavior when no selection exists at all, but otherwise it is sufficient to invoke correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description mentions selectionVersion, which is a returned value meant to be threaded into a later call rather than an input here — useful but slightly ambiguous about where it gets passed.

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: 'Read the currently selected star and its selectionVersion', which tells an agent exactly what comes back. It does not explicitly contrast with siblings such as soclo_actors_list or soclo_actors_select, so the reader must infer that this returns only the active selection rather than a collection.

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?

'Free; changes nothing and charges nothing' gives a reason to prefer this over costlier calls, but there is no explicit statement of when to use it versus soclo_actors_list or soclo_actors_select. Usage is only implied: fetch the current selection, likely before calling select.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still adds real value by stating there is no charge ('Free; changes nothing and charges nothing') and by naming the pricing/version/capacity fields the call surfaces, which the agent would otherwise not expect from a 'list roster' tool.

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

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

A single sentence, front-loaded with the primary payload and the secondary offer details, followed by a short cost/side-effect clause. Nothing is wasted and nothing essential is deferred.

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

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

With no parameters and no output schema, the description carries the burden of describing returns, and it does name the roster plus the pricing tuple. It is slightly thin on what a roster entry contains and on whether the offer is per-actor or global, which matters for a zero-input 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?

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly adds no param noise.

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

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

Specific verb 'Return' with a clearly scoped resource ('your owned fictional presenter roster') plus a second stated payload (live creation offer: prices, pricing version, capacity). It is easy to distinguish from soclo_actors_create or soclo_actors_remove, though it never explicitly contrasts with soclo_actors_current, which is the nearest ambiguous 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 'roster' (list what you own) rather than stated, and there is no explicit 'use this instead of X' routing. The agent must infer the list-vs-current distinction from the tool name alone.

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

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

Adds substantial context beyond the annotations: the operation is free, the preview requires approval before revocation, retries should reuse a stable clientRequestId and preserve expectedSelectionVersion, and delayed private cleanup preserves in-flight jobs. These details clarify safety and lifecycle behavior for a destructive but idempotent 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?

Short and front-loaded: preview/approval comes first, followed by required identifiers and then cost and cleanup behavior. Every sentence contributes operational meaning without waste.

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

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

For a destructive, idempotent mutation with no output schema and high schema coverage, the description provides the essential workflow, identifier sourcing, retry stability, cost, and cleanup semantics needed to call it correctly.

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

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

Schema coverage is 80%, so the schema carries most parameter meaning. The description still adds useful semantics by specifying that actorVersion must be the original value, expectedSelectionVersion must be concrete from soclo_actors_current, and clientRequestId must be stable across retries.

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 action and resource: preview an actor, then with confirm: true revoke future use. This clearly distinguishes it from sibling tools like soclo_actors_list, soclo_actors_current, soclo_actors_create, and soclo_actors_select.

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

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

Explains the required two-step usage pattern: preview for approval, then pass confirm: true to revoke. It also specifies where actorVersion and expectedSelectionVersion should come from, but does not explicitly compare this tool against non-removal alternatives.

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 real context beyond the annotations: no cost, owner-consent requirement, a stable clientRequestId for idempotency (consistent with idempotentHint=true), and the fact that the current selection version is read on the caller's behalf. The notable gap is that destructiveHint=true is never explained — the description doesn't say the previous selection is replaced or lost, which is exactly what an agent needs before a destructive call.

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

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

Three short sentences, front-loaded with purpose, then cost/consent constraint, then the idempotency and recovery mechanics. No sentence is filler and nothing is buried.

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

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

For a destructive, non-read-only mutation with no output schema, the description covers cost, consent, idempotency, concurrency handling and failure recovery. It stops short of saying what state the selection overwrites or what is returned, which leaves one meaningful hole.

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

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

Schema coverage is 67%: actorId and actorVersion are documented in-schema, while clientRequestId is bare. The description compensates by telling the agent to pass a *stable* clientRequestId (retry semantics) and by reinforcing that actorVersion must be the current one from soclo_actors_list.

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 — select an owned, ready actor to reuse in future adverts — and pins down the source of the two identifiers (actorId and current actorVersion from soclo_actors_list). An agent can distinguish this from soclo_actors_list, soclo_actors_current, soclo_actors_create and soclo_actors_remove without opening any schema.

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

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

Gives an explicit consent gate ("only when the owner asks"), a cost signal ("Free"), and a named recovery path: read soclo_actors_current after an uncertain result before choosing again. That is when-to-use, a when-not, and a sibling alternative all in two sentences.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds useful context: it is free, does not trigger synthesis, does not change any selection, returns absence explicitly, and returns no provider access token. These are meaningful behavioral details beyond the structured hints.

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

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

The definition is front-loaded and only two sentences long, with no wasted preamble. The second sentence is dense with internal terminology around host plan import and selectedInput.voices, which slightly reduces clarity despite the efficient 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?

For a simple two-parameter read tool, the description covers cost, side effects, absence behavior, and a key alternative for a related carrier use case. Since there is no output schema, it would ideally describe the return shape more fully, but the core behavioral context is present.

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

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

Schema description coverage is 100%, and the schema already explains that actorId and actorVersion come from soclo_actors_list. The description reinforces that both must refer to an owned actor, but adds no additional format or usage detail beyond the schema baseline.

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

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

The description states a specific verb and resource: 'Read the exact saved default voice' for an owned actorId and actorVersion. It also distinguishes the tool from soclo_hosted_voices_autoload by naming that sibling for a different need, the saved actorVoice carrier for host plan import.

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—free, read-only, no synthesis—and explicitly redirects the host-plan-carrier use case to soclo_hosted_voices_autoload. It does not fully state when not to use this tool or spell out prerequisites beyond ownership.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds real value by bounding that destructiveness ('budget, audience and words do not change'), stating the cost ('Free'), and describing the non-attaching fallback of returning a link. It does not say whether an applied link change is revertible, which is the main remaining behavioral unknown for a live-ad 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?

Front-loaded with the primary action and its platform condition, then fallback, cost, and the confirm rule — no filler sentences. Slightly dense packaging (bare 'Free.' fragment, inline platform list) keeps it just short of ideal.

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

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

For a two-parameter mutation with full schema coverage and no output schema, the description covers the key facts an agent needs: what changes, what does not, when it degrades to a manual paste link, and the preview gate. Missing only the revert path and a pointer to the sibling tool for unsupported platforms.

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

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

Schema coverage is 100% and the confirm parameter description already carries the preview-after-owner-approval semantics, so the schema does the heavy lifting. The description restates the confirm preview rule but says nothing extra about the id parameter or its provenance.

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 — pointing a live ad at its page link — and scopes it to the platforms that permit a link-only change (Meta, TikTok, Google Search/Display), with the fallback spelled out. An agent can tell this apart from sibling edit/publish tools without opening their schemas.

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

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

The 'Without confirm:true it is a preview' clause plus the platform-support branch gives a clear preview-then-apply protocol and tells the agent what happens when the platform does not allow the change. It stops short of naming alternatives (e.g., soclo_ad_pages_edit) for the unsupported case, so the routing is implied rather than explicit.

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

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

The description goes well beyond the annotations by explaining that credits are spent once, never charged twice, and that one page exists per ad version. It also discloses the asynchronous operation pattern: follow the returned opId until it settles, then preview.

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

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

The description is four tight sentences with no filler. It front-loads the action and cost, then states the approval prerequisite, idempotency guarantee, and follow-up step in a logical order.

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 9-parameter, nested-object, asynchronous mutation tool with no output schema, the description covers the critical missing context: cost, approval gate, idempotency, opId follow-up, and next preview step. An agent can call this correctly without opening additional documentation.

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

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

Schema coverage is already 100%, so the schema carries most parameter meaning. The description still adds useful semantics around the identity parameters by tying repetition and charging to the ad version, and it reinforces that credits and pricingVersion come from an approved quote.

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

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

The description states a specific verb and resource: it writes a page matching the ad, saves it on the owner's website, and keeps it out of the menu and unlinked. That level of scope detail distinguishes it from siblings such as quote, preview, attach, and publish.

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

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

It clearly gates invocation on owner approval of a quote and tells the caller to repeat safely because the operation is idempotent. It also points to the next step, following the returned opId and then previewing, though it does not explicitly name sibling tools or state when not to use this tool.

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

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

Annotations already declare this as a non-readonly, destructive, non-idempotent operation, so the description does not need to repeat those safety traits. It adds useful context that the edit is free and immediately visible on a live page, but it omits reversibility, permission requirements, and what exactly is overwritten.

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

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

The description is short and front-loads the core action, with no wasted sentences. 'Free' and the live-page note are useful, though 'page words' is slightly vague.

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

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

For a destructive nested-object edit tool with no output schema and low parameter description coverage, the description is too sparse. It mentions cost and immediate visibility but does not explain which page sections can be changed or how partial edits are handled.

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 only 25%, and the description does not compensate by explaining the id, hero, cta, or about parameters. 'Page words' hints at text fields but gives no mapping to the nested objects or partial-update behavior.

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

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

The description states a clear verb and resource: changing the words on an ad page. It does not explicitly differentiate this edit tool from siblings like create, publish, preview, or reject, but the core action is still 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?

The phrase 'the owner asked for' implies this is used when the owner requests copy changes, but there is no explicit guidance on when to use this versus create, publish, preview, or other page tools. No exclusions or alternatives are named.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world. The description adds non-obvious behavioral context: the enquiry figures cover the entire site within the page's live window, not only enquiries attributable to this ad. It does not mention rate limits or error behavior, but the annotations cover the safety profile.

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

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

The description is a single tightly written sentence with the returned fields front-loaded and a parenthetical that earns its place by clarifying the enquiry scope. There is no redundant restatement of the title 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?

Because there is no output schema, the description appropriately summarizes what the call returns and clarifies the important enquiry aggregation window. It is nearly complete for a simple read-by-id tool; only minor details such as not-found behavior are left implicit.

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

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

Schema description coverage is 100%, and the schema already explains that the required id comes from soclo_ad_pages_list or a create result. The description does not add any further meaning about the id parameter, so the baseline 3 applies.

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

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

The description clearly states it retrieves a single ad page and enumerates the returned content (words, state, link, clicks, enquiries). It distinguishes itself from list-style siblings by saying "One ad page," though it does not explicitly mention alternatives like soclo_ad_pages_list.

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

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

Usage is implied by the singular scope, but the description does not say when to use this versus soclo_ad_pages_list or when a specific page should be fetched rather than previewed or edited. No explicit when-not guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful context about what the response contains (state, link, click count), but says nothing about pagination, page limits, or whose 'owner' is resolved (account/actor context).

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

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

A single short sentence with zero filler, front-loading the resource and then the fields of interest. Nothing could be cut without losing information.

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

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

For a parameterless read tool with rich annotations and no output schema, the description covers the resource and the shape of the returned data. It stops short of stating pagination behavior or how 'owner' is scoped, which would matter for a list endpoint returning a variable number of items.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description instead usefully characterizes the returned fields, which compensates for the absent output 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 identifies the resource (the owner's ad pages) and enumerates the key fields returned (state, link, clicks). It lacks an explicit verb and doesn't distinguish itself from siblings like soclo_ad_pages_get or soclo_ad_pages_preview, but the listing intent is clear from the plural resource plus the tool 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?

There is no statement of when to use this versus soclo_ad_pages_get (single page) or soclo_ad_pages_preview, and no prerequisites or exclusions are given. The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds two genuinely new facts – the return is rendered HTML and the call is free – which is useful context beyond the schema, but it says nothing about how the HTML is delivered (inline string vs. URL) or about pagination/size limits.

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

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

Two short fragments with no filler, and the core deliverable is front-loaded in the first clause. Slightly clipped to the point of losing the action verb, but nothing is redundant.

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

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

For a single-parameter read tool with full annotation coverage, the description plus schema is close to sufficient. However, with no output schema present, the description should clarify the shape of the returned HTML (inline vs. link, whether it is a full document), which it leaves ambiguous.

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

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

Schema description coverage is 100% and the only parameter 'id' is documented with its source (soclo_ad_pages_list or a create result). The description adds no parameter meaning at all, so the baseline 3 applies when the schema carries the full burden.

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

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

The description states the artifact produced ('the rendered page HTML') and the audience ('the owner'), implying a preview/read of an existing ad page. But it omits the verb and never distinguishes this from adjacent siblings such as soclo_ad_pages_get or soclo_page_preview, so an agent must infer that this renders rather than fetches structured data.

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

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

'before publishing' gives a usable timing cue that ties the tool to the publish flow. There is still no explicit guidance on when to prefer this over soclo_ad_pages_get or soclo_ads_get_ad_previews, so the 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?

Adds context annotations don't carry: it runs the website's own checks before going live, returns a tracked link, is free, and prompts for confirmation rather than silently taking the site live. It doesn't address irreversibility or the destructiveHint/non-idempotent nature, leaving one meaningful gap.

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

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

Three short sentences: effect and return value first, cost second, the risky conditional last. No filler, and the dangerous parameter guidance is placed where it will be read before acting.

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

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

Covers pre-flight checks, the returned tracked link, cost, and the consent gate for site-wide publishing — enough for a 2-param mutation with no output schema. A note on whether publishing is reversible would close the remaining gap.

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

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

Schema coverage is 100% and the takeSiteLive consent rule is already stated in the schema description, so the description adds little parameter meaning beyond restating it; the implicit gating behavior is the only added value.

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

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

Specific verb+resource: 'makes the page live and returns its tracked link' clearly identifies publishing an ad page and its outcome. It doesn't name the sibling it differs from (soclo_page_publish for site pages, soclo_ad_pages_preview), but the ad-page scope is unambiguous from the name and description.

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

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

Gives a clear conditional rule for the risky path: pass takeSiteLive:true only after the owner agreed to put the whole website live, and notes the tool asks first when the site isn't live. No exclusion guidance relative to preview/reject siblings, so not a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description still adds real behavioral context: it is free, it costs nothing when a matching page already exists, it never creates a picture, and any removal of an old page requires the owner's explicit say-so. That is meaningful disclosure beyond the structured hints for a quoting tool.

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

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

Front-loads the key fact ('Free') and the core behavior in the first sentence, with the operational instruction last. The makeRoom sentence is a slight digression but earns its place by covering the site-full edge case; nothing is redundant.

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

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

There is no output schema, so the description must carry the return values, and it names the three that matter (price, existing-page check, site readiness). For a 7-parameter nested-schema tool that is adequate, though the exact response shape and how platform/accountId affect the quote are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining the two input paths — a live adId is read by Soclo, while a draft supplies its own words via the ad object and draftId — which is the non-obvious semantics an agent needs. It does not touch accountId/adAccountId/libraryAssetId, leaving those entirely to the schema.

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

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

States a specific verb (quote) and resource (a page for an ad) and immediately says what the result is: the credit price for a matching page on the owner's Soclo website. It also names two extra return facts (whether an identical page already exists, whether the site is ready), which separates it cleanly from soclo_ad_pages_create and soclo_ad_pages_preview.

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 closing line 'Show the owner the price before create' gives an explicit ordering rule that routes the agent to this tool ahead of soclo_ad_pages_create. The capacity paragraph explains the fallback path (makeRoom, offer to the owner, remove only on their say-so), but no explicit when-not condition or alternative quote tool is named, so it stops short of a full 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real value beyond them: the operation is free, and the credits spent creating the page are NOT returned, which tells the agent the cost consequence is irreversible. It does not state whether the removal can be undone or restored, leaving one gap.

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

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

Three short sentences, front-loaded with the action, followed by the scope caveat, cost consequence, and the one parameter hint. Every sentence carries information; nothing is padded.

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

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

For a 2-parameter destructive mutation with no output schema and full annotation coverage, the description supplies the missing cost/irreversibility context an agent needs. It stops short of stating recovery options or what the tool returns, a modest but 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 100%, so both `id` and `reason` are already documented in the schema, including the make_room explanation. The description's mention of make_room largely repeats the schema rather than extending it (no guidance on the 'owner' value or on how id is obtained).

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

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

Names a specific verb+resource ('Removes this ad page') and scopes it tightly to 'only the page Soclo made for the ad', which separates it from generic page removal. It never names the near-sibling soclo_page_remove or other ad_page operations (edit/list/get), so differentiation is implied by scope rather than stated.

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

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

The only routing guidance is embedded in the parameter note: 'Use reason make_room when it frees space for a new ad page.' There is no statement of when to prefer this over soclo_page_remove or soclo_ad_pages_edit, and no prerequisites or when-not conditions.

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

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

Annotations already flag destructive=true, non-idempotent, and open-world; the description adds approval gating, confirm:true after preview, requestId reuse for confirmation/recovery, and checking live status. It remains vague about what 'deletion' means for an add-callouts operation, but it substantially improves behavioral understanding.

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

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

The description is short and front-loads the purpose, then the safety workflow. Cryptic fragments such as 'Spending/deletion' and the raw documentation URI slightly reduce clarity, but there is little wasted prose.

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

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

For a destructive 10-parameter nested-write tool with no output schema, it supplies the critical approval and confirmation flow but leaves major gaps around payload/callout structure and how to preview or check operation status. It is adequate but incomplete.

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

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

Schema description coverage is only 60%, yet the description adds little beyond the schema: it repeats confirm and requestId guidance that the schema already documents. It does not explain the required payload.callouts array, its length/count constraints, platform, parameters, or the expected* preview fields.

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

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

The description states a specific verb and resource ('Add account callouts') for Soclo Ads, making it distinguishable from list/update/remove callout siblings. It does not explicitly name alternatives, but the purpose is clear from the action and resource.

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

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

It gives an important preview-then-owner-approved-confirm workflow with the same requestId, which is useful context. However, it does not say when to use this tool versus update_account_callouts or remove_account_callout, nor how to obtain the required preview.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds context the annotations cannot: a mandatory preview step, owner approval via confirm:true, requestId reuse for confirmation/recovery, and that the claim is only live once status is active. This is meaningful workflow context beyond the structured hints, though it does not explain what exactly gets destroyed or how it affects existing sitelinks.

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

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

It is short and front-loads the purpose, which is good. But the fragments are telegraphic ('Claim live only when status is active' is ambiguous about what 'claim' means), and the trailing 'Fields: soclo://tools/...' self-reference is opaque filler that does not help an agent act.

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 approval/preview workflow is covered, which is the critical safety piece for a destructive, non-idempotent mutation. Missing for a 10-param nested tool with no output schema: whether sitelinks are appended or replace the account's set, how the expected* budget/currency fields relate to sitelinks at all, and where the preview originates.

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 60%, so the schema already documents confirm, requestId, adAccountId, and the expected* fields. The description mentions confirm and requestId but only restates what the schema properties already say, and adds nothing about the nested payload.sitelinks shape (text, linkUrl, description lengths, maxItems 20) or the purpose of the expectedCurrency/expectedBudget* fields for a sitelink operation.

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

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

The first sentence names a specific verb and resource ('Add account sitelinks'), so the operation is unambiguous. However, it offers no differentiation from the very similar siblings soclo_ads_update_account_sitelinks, soclo_ads_remove_account_sitelink, and soclo_ads_add_account_callouts/structured_snippets.

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

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

It states a procedural rule ('preview, then owner-approved confirm:true with the same requestId'), which is real usage guidance for the approval path. But it never says when to choose this tool over update_account_sitelinks or remove_account_sitelink, and it does not name the preview tool to call 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 flag destructiveHint=true and idempotentHint=false, but the description adds value the annotations cannot: this is a two-phase operation requiring an owner-approved preview and a reused requestId, and the result is only live once status is active. What it omits is whether adding appends to or replaces existing snippets, and what a failure response looks like.

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

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

It is short and front-loads the purpose before the workflow constraint, which is good. But the trailing "Fields: soclo://tools/..." pointer is opaque and the phrase "Claim live" is jargon that costs a sentence without conveying anything actionable.

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, 10-parameter mutation with no output schema, the description covers the highest-risk element, the owner-approval/confirm handshake and requestId reuse. It falls short on what scope "account" means, whether existing snippets are replaced, and how to recover an outcome, but the critical safety story is present.

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

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

Schema description coverage is 60%, so the schema carries most of the load, including the nested payload shape (header enum, 3-10 values of up to 25 chars). The description adds no parameter meaning beyond echoing confirm and requestId, and says nothing about the many uncovered or seemingly irrelevant parameters (platform, parameters, expectedCurrency/expectedBudgetType/expectedBudgetAmount) for a snippets operation.

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

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

The description gives a specific verb and resource ("Add account snippets") for a Soclo Ads account, which is distinguishable from the neighboring add/update/remove asset tools by verb alone. It never differentiates against siblings such as soclo_ads_update_account_structured_snippets, soclo_ads_remove_account_structured_snippet, or soclo_ads_add_account_sitelinks/callouts, and it doesn't describe what a structured snippet is.

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?

"Spending/deletion: preview, then owner-approved confirm:true with the same requestId" gives a real precondition for calling, and "Claim live only when status is active" implies a follow-up status check. However, there is no guidance on checking existing snippets via soclo_ads_list_account_structured_snippets first, nor on choosing add versus update, and the exclusions are left implicit.

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, the description discloses a preview/approval flow, the need to reuse the same requestId, and that claims should only be considered live when status is active. This adds useful mutation-safety context, though it does not elaborate on spend implications or failure behavior.

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

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

The description is short and front-loads the core purpose and confirmation workflow. The final 'Fields: soclo://...' pointer is cryptic and does not clearly earn its place, but otherwise it 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?

This is a complex destructive mutation with 10 parameters, nested payload objects, and no output schema. The description covers the confirmation protocol but leaves key payload semantics, keyword structure, match types, negative keywords, and validation boundaries 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 only 60%, and the description adds meaning mainly for confirm and requestId. It does not explain the core payload parameters such as adSetId, keywords, matchType, or negative, nor other parameters like platform or accountId.

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

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

The description states a specific verb and resource: 'Add Search ad-group keywords.' This is clear, but it does not explicitly differentiate the tool from siblings such as soclo_ads_update_ad_keyword, soclo_ads_remove_ad_keyword, or soclo_ads_list_ad_keywords.

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 confirmation workflow ('preview, then owner-approved confirm:true with the same requestId') and a status condition, which implies when confirmation is appropriate. However, it does not state when to use this tool versus related add/update/remove keyword tools or what prerequisites are required.

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

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

Annotations already flag destructive=true, idempotent=false, and openWorld=true. The description adds genuinely new behavior: a preview-then-confirm approval gate tied to requestId reuse, and the condition that the change is only live once status is active. This is valuable beyond the annotations, though the mechanism remains somewhat terse.

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

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

The description is short and front-loads the action, followed by the critical approval flow. The trailing 'Fields: soclo://...' pointer is slightly cryptic but keeps the description compact.

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 10-parameter destructive mutation with no output schema, the description covers the crucial confirmation/recovery flow but omits key specifics an agent would want: the nested users payload shape (email/phone, 10k cap), the role of platform/adAccountId, and how to verify the 'active' status afterward.

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 60%, so baseline is 3. The description reiterates confirm and requestId semantics that the schema already documents, and defers the rest to an external doc URL ('Fields: soclo://...'), adding little new meaning for the undocumented parameters such as audienceId, payload.users, and platform.

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

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

The description clearly states a specific verb and resource: adding users to an ad audience. It does not explicitly differentiate from close siblings like soclo_ads_update_ad_audience or soclo_ads_replace_ad_audience_companies, but the action is unambiguous.

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

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

The description supplies an operational workflow (preview, owner-approved confirm:true, same requestId, claim live only when status is active), which is useful usage context. However, it gives no guidance on when to choose this tool over write-alternatives like replace_ad_audience_companies or update_ad_audience.

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

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

Annotations already declare destructive=true, idempotent=false and openWorld=true, but the description adds real value beyond them: it reveals the mandatory preview/owner-approval flow, the requestId-reuse requirement for confirmation and recovery, and that the claim goes live only when status is active. It stops short of detailing what exactly is deleted/changed 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?

Content is front-loaded and terse, with the critical spending/confirm constraint stated before the trailing 'Fields: solco://...' reference. The final resource-pointer sentence is cryptic and of questionable value but does not bloat the description materially.

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

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

For a destructive, non-idempotent mutation with nested objects and no output schema, the definition covers the essential safety workflow (preview → approved confirm → active status). It leaves gaps: it doesn't describe the adjustments payload semantics or how/where to check the 'active' status (likely soclo_ads_operation_status), so an agent still needs to discover recovery/status mechanics 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?

With 60% schema coverage, the schema already documents confirm, requestId, adAccountId, expectedCurrency/BudgetType/BudgetAmount. The description reinforces confirm and requestId reuse but largely restates them, and adds no meaning for the undocumented nested payload/adjustments structure. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource: 'Adjust uploaded conversions.' This is concrete enough to distinguish from generic update tools, but it never names or contrasts with close siblings like soclo_ads_send_conversions or soclo_ads_update_conversion_action, leaving the agent to infer which conversion tool to use.

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 preview-then-confirm workflow ('preview, then owner-approved confirm:true with the same requestId') implies a required sequencing for spending/deletion changes, which is useful. However, it gives no explicit when-to-use-this-vs-alternatives guidance (e.g., send_conversions vs adjust_conversions), so the routing decision is left implicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the concrete operational consequence (spending and deletion changes) and the approval gate an agent must clear before calling it. 'Claim live only when status is active' hints at an asynchronous outcome state, which is useful context not present in any annotation.

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

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

Short and front-loaded with the safety-critical rule first, which is right. But the fragment style ('Claim live only when status is active', 'Fields: soclo://tools/...') is cryptic rather than dense, and the trailing URL pointer is a reference stub rather than 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?

The most important thing - that this mutates live campaigns and requires preview plus owner approval - is covered. Missing for a 10-parameter, nested-payload, destructive tool with no output schema: what 'apply' actually changes per recommendation type, the maxItems:100 batch limit, how to obtain valid resourceNames, and how to poll the outcome via operation_status.

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 60% across 10 parameters. The description only touches confirm and requestId, and both are already documented in the schema ('True only after owner approval of spending/deletion preview', 'Reuse this request ID for confirmation'). It says nothing about the nested payload.recommendations resourceName array, the expectedCurrency/expectedBudgetAmount matching requirement, or adAccountId versus accountId - leaving the 40% coverage gap unfilled.

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

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

States a specific verb and resource ('Apply Google Ads recommendations'), which is clear on its own. However it never distinguishes itself from the closely named siblings soclo_ads_list_google_recommendations and soclo_ads_dismiss_google_recommendations, so an agent must infer that this is the one that actually commits changes.

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 real procedural guidance for the risky path: spending/deletion changes must be previewed first, then confirmed with confirm:true and the same requestId. What it omits is the entry point - nothing says the recommendation resourceNames come from list_google_recommendations, and no alternative or exclusion is named against dismiss.

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 description sensibly spends its words on what annotations cannot say: the approval gate before confirming and the requestId reuse contract. 'Claim live only when status is active' hints at a state precondition but is too compressed to be fully actionable, and it never says whether archived forms are recoverable.

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

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

It is short and front-loaded with the workflow constraint, but the style is telegraphic: the 'Soclo Ads:' prefix is noise, 'Claim live only when status is active' is opaque jargon, and 'Fields: soclo://tools/...' redirects the reader elsewhere. Brevity here costs comprehension rather than adding it.

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

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

For a destructive, open-world mutation with six parameters, a nested object and no output schema, the description covers the approval protocol but omits what archiving actually does to the form and its leads, how accountId relates to adAccountId, and what the caller gets back. It is adequate to avoid a wrong call, not complete enough to call with confidence.

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

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

Schema coverage is only 50%, yet the description only mentions confirm and requestId — both of which the schema already documents in its own descriptions. The undocumented parameters (platform, accountId vs adAccountId, and the nested parameters.formId) get no clarification in the description, so the coverage gap is not compensated.

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 ('Archive a lead form'), which clearly separates it from siblings like soclo_ads_create_lead_form, soclo_ads_get_lead_form and soclo_ads_list_lead_forms. It does not clarify how archiving differs from deletion or what archiving means for already-collected leads, 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?

It states a concrete operating procedure — preview the deletion, obtain owner approval, then re-issue with confirm:true and the same requestId — which is exactly the guidance an agent needs before calling a destructive tool. It gives no alternatives or exclusions (e.g., when to leave a form active instead of archiving), so it is clear context rather than full routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the preview→owner-approved confirm:true flow, requestId reuse for confirmation/outcome recovery, and that the claim only goes live when status is active — exactly the kind of operational behavior an agent needs for a destructive 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?

The purpose is front-loaded and the passage is very short with no filler. The trailing 'Fields: soclo://tools/...' pointer is a bit cryptic, but overall it is tight and efficiently ordered.

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

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

For a destructive, non-idempotent mutation with a nested payload, 10 params, and no output schema, the description is too thin. It explains the confirm gate but not what the assignment actually does to existing access, what the payload tasks (MANAGE/ADVERTISE/ANALYZE/DRAFT) control, or how the expected* fields factor into the preview/confirm flow.

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 10 parameters at 60% schema coverage and a nested payload object, the description carries real gaps to fill, but it only clarifies the meaning of 'confirm' and 'requestId' indirectly. It leaves payload.userId/payload.tasks, accountId, platform, and the expectedCurrency/expectedBudgetType/expectedBudgetAmount pair unexplained beyond what the schema already shows.

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

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

States a specific verb and resource ('Assign a user to an ad account'), which is clearly distinguishable from the sibling soclo_ads_remove_ad_account_user. It doesn't explicitly name or differentiate against list/invite sibling tools, but the core action is unambiguous.

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

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

The description implies a gated workflow ('preview, then owner-approved confirm:true with the same requestId'), which is useful usage context, but never states when to choose this tool over alternatives like soclo_ads_invite_ad_account_to_manager or soclo_ads_list_ad_account_users, and offers no exclusions.

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

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

Annotations already declare destructive/openWorld behavior, but the description adds useful workflow context: a preview-then-confirm sequence, requestId reuse, and a condition that the claim is live only when status is active. This is additional value beyond the structured hints, though it still does not explain exactly what access is granted or revoked.

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

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

The description is short and front-loads the purpose, with no wasted sentences. The 'Fields: soclo://...' reference and 'Claim live only when status is active' are somewhat cryptic but do not bloat the text.

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

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

For a destructive 10-parameter nested mutation, the description covers the critical confirmation workflow but omits parameter-level detail, alternative-tool guidance, and any post-confirmation status/recovery explanation beyond the requestId hint.

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 60%, and the description only echoes the confirm and requestId workflows already documented in the schema. It adds no meaning for pageId, userId, businessId, tasks, accountId, or the expected* preview fields.

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

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

The description states a specific verb and resource: 'Assign a user to a Page.' It is clear what the tool does, but it does not distinguish this tool from nearby siblings such as soclo_ads_assign_ad_account_user or soclo_ads_remove_page_user.

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 procedural guidance ('preview, then owner-approved confirm:true with the same requestId') but does not say when to use this tool versus alternatives, nor does it mention prerequisites such as listing existing page users 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 and openWorldHint=true, but the description adds the important non-obvious behavior: spending/deletion requires a prior preview and an owner-approved confirm:true reusing the requestId, and claims are live only when status is active. That is genuine context beyond annotations, though the recovery path (how to check status via operation_status) is unnamed.

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

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

Front-loaded and short with no filler prose, but the trailing "Fields: soclo://tools/soclo_ads_attach_ad_group_assets" is an opaque reference that earns no place without explanation. The safety rule is compressed to near-telegraphic phrasing.

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, spend-affecting, 10-parameter nested mutation with no output schema, the safety gate is covered but much is not: what a successful attach returns, how to verify the 'status is active' claim, and which tool produces the required preview. Adequate minimum, clearly 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 60%, and the description names no parameters at all. The only parameter-related concepts it touches (confirm, requestId reuse) are already spelled out verbatim in the schema, so it adds nothing. The large nested payload (images, callouts, sitelinks, structuredSnippets) and its constraints are left entirely to the schema with no explanatory framing.

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

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

The verb+resource ("Attach ad-group assets") is stated, but it is essentially a restatement of the title/name, with no scope detail. Siblings soclo_ads_update_ad_group_assets, soclo_ads_remove_ad_group_assets, and soclo_ads_attach_campaign_assets are never distinguished, so the agent cannot tell what 'attach' covers here versus update/remove.

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 real workflow rule (preview first, then owner-approved confirm:true with the same requestId) which implies when this tool may be called. But it never says when to prefer update_ad_group_assets over attach, or what prerequisites (account connection, ad set existence) are required.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety bar is lower. The description adds the confirm/requestId recovery flow and a status condition, but the 'Spending/deletion' framing is clearly boilerplate for a labeling operation and never discloses that up to 1000 entities per type can be mutated in a single call or that repeats are non-idempotent.

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

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

It is short, but a third of it is low-signal boilerplate ('Soclo Ads:' prefix, spending/deletion template, and a 'Fields: soclo://tools/...' pointer) rather than front-loading what actually gets labeled.

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 10 parameters, nested payload objects and no output schema, the description should clarify scope, entity types, and how to check the outcome. It mentions 'status is active' without pointing to soclo_ads_operation_status for polling, and the budget/currency parameters go 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 coverage is only 60% and the description explains no parameters. It says nothing about labelId in `parameters`, the payload arrays, or why currency/budget fields (expectedCurrency, expectedBudgetAmount, expectedBudgetType) appear in a label-attachment request, leaving a significant ambiguity unresolved.

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

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

The verb+resource ('Attach a Google Ads label') is clear, but the description never says what the label is attached to. The schema reveals adIds, adSetIds, keywordIds and campaignIds, yet the description leaves the agent to discover that this is a bulk labeling operation across four entity types. It also does not distinguish it from soclo_ads_update_ad_label or soclo_ads_detach_ad_label.

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 procedural guidance is a generic 'preview, then owner-approved confirm:true with the same requestId' boilerplate about spending/deletion, which does not tell the agent when to use label attachment versus updating or detaching a label. No preconditions about needing an existing labelId from create/list are 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, idempotentHint=false and openWorldHint=true, so the safety bar is lowered, and the description still adds meaningful process context: a preview-before-confirm gate, confirmation tied to a reused requestId, and the rule that the claim is live only at active status. It does not say what specifically can be destroyed by a bad attach or how failures surface, which keeps it below a 5.

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

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

Three short clauses, front-loaded with the verb and immediately followed by the risk/confirmation rule — there is no padding. The telegraphic style and the unresolved URI reference cost it a point, since the reader has to decode rather than simply read.

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

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

For a 10-parameter, destructive, nested-payload mutation with no output schema, the description is too thin: it never enumerates the attachable asset types, whether attaching is additive or replacing, per-platform constraints, or what the caller gets back to track the operation. The pointer to an external field reference defers the substance rather than supplying it.

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 60%, so the schema carries most of the weight; the description reinforces confirm and requestId semantics in prose. The nested payload properties (images, callouts, sitelinks, structuredSnippets) have no descriptions in either the schema or the description, and the only help offered is an opaque pointer, "Fields: soclo://tools/soclo_ads_attach_campaign_assets."

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?

"Attach campaign assets" states a specific verb and resource, and the verb distinguishes it from soclo_ads_remove_campaign_assets and soclo_ads_update_campaign_assets. However, the sentence is essentially a restatement of the title with no scope detail: it never says what kinds of assets (images, callouts, sitelinks, structured snippets) or at what level (campaign vs ad group) they are attached.

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 does give a real workflow: preview first, then call again with owner-approved confirm:true and the same requestId, and treat the claim as live only once status is active. What it omits is which tool provides the preview and which one returns status — presumably soclo_ads_operation_status — so the agent must infer the routing rather than being told.

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, openWorldHint=true, idempotentHint=false), the description discloses the preview-then-confirm gate, that owner approval is required, that the same requestId must be reused, and that a claim only goes live when status is active. That is real behavioral context the annotations do not carry. It omits failure/partial-success behavior for a 5000-item batch.

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 mutation and its safety workflow are front-loaded in three short sentences with no filler. The trailing 'Fields: soclo://tools/...' pointer is a compact but opaque reference that costs a line without obvious payoff for an agent.

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 bulk mutation with 10 parameters, a nested request array, no output schema, and idempotency disabled, the description covers the approval gate but leaves out batching limits, partial-failure semantics, catalog scoping, and how to check outcome beyond reusing requestId. Adequate but meaningfully short of what an agent needs to invoke this safely.

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

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

Schema coverage is 60%, so some parameters already carry descriptions. The description adds meaning for 'confirm' (only after owner-approved preview) and 'requestId' (reuse for confirmation and outcome recovery), but it says nothing about the nesting of payload.requests, the CREATE/UPDATE/DELETE method field, catalogId vs catalogAccountId, or the 5000-item cap, leaving half the surface 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?

The description states a clear verb set and resource: create/update/delete products in bulk. The word 'bulk' implicitly distinguishes it from the single-item siblings soclo_ads_create_ad_catalog_product, update_ad_catalog_product and delete_ad_catalog_product, but it never names them, so the differentiation is inferential rather than explicit.

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

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

It gives a concrete workflow for the destructive path ('preview, then owner-approved confirm:true with the same requestId'), which is genuinely useful. It says nothing, however, about when to choose this tool over the per-product siblings or when a bulk call is inappropriate (e.g. large arrays), so alternative selection is left 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, openWorldHint=true, idempotentHint=false; the description adds substantial non-obvious behavior: the two-phase quote/confirm pattern, the spending-approval gate, the cost of an accidental repeat, and that 'created' does not mean 'live' because platform review can delay delivery. That is real operational context an agent could not infer 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?

Front-loaded with purpose, then a tight sequence of workflow-critical sentences with no filler. The trailing 'Fields: soclo://tools/soclo_ads_boost_post.' is vestigial and adds nothing, the one clear 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?

No output schema exists, so the description takes on return-value semantics itself: it describes the spending preview, the returned status, and the difference between confirmed/active and pending platform review. Combined with the confirmation loop and recovery path, an agent has everything needed to call this safely.

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

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

Schema coverage is only 60% and the payload subproperties are largely undescribed, so the description must compensate — it does so for the critical ones (goal, targeting, budget, postId/platformPostId, confirm, requestId) and adds the non-obvious rule that an X video post takes postId or platformPostId. It leaves expectedCurrency/expectedBudgetAmount and adAccountId unaddressed (those do carry schema descriptions).

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

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

States a specific verb+resource+scope: promote an EXISTING post as a PAID advertisement with goal/targeting/budget, which distinguishes it from creation siblings like soclo_ads_create_standalone_ad or soclo_ads_create_ad_campaign. It never names those siblings explicitly, so differentiation is inferential rather than stated.

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

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

Gives an explicit conditional workflow: call without confirm:true to get a quote, show the spending preview, obtain owner approval, then confirm with the same requestId. It also names the follow-up tool (soclo_ads_operation_status) for uncertain results and states an exclusion (never automatically repeat a purchase).

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds valuable behavioral context: spending/deletion impact, the need for a preview and owner-approved confirm:true with the same requestId, and the status condition for going live. It does not detail what exactly gets destroyed (e.g., campaign delivery) or auth requirements, but provides meaningful supplement beyond annotations.

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

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

The description is short and front-loaded with the core action, followed by critical safety workflow. The final line 'Fields: soclo://...' is cryptic and may not earn its place, but overall it is appropriately sized with minimal waste.

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

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

For a destructive bulk tool with 10 parameters, nested objects, and no output schema, the description is insufficient. It omits the structure of the 'payload' (campaigns array, max 50, platform enum), the role of accountId and budget fields, and how to handle errors. The brief mention of a fields URI does not compensate for the missing explanation, leaving an agent under-informed.

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 60%, so the baseline is 3. The description adds meaning to the 'confirm' and 'requestId' parameters by explaining the preview/approval flow, but does not clarify the required 'payload' structure (campaigns array, maxItems, platform enum) or the expected budget fields. Beyond those few parameters, it leaves the schema to carry the burden.

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

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

The description states a specific verb ('Pause or resume') and resource ('many campaigns'), and the use of 'many' implicitly distinguishes it from the singular sibling tool soclo_ads_update_ad_campaign_status. However, it does not explicitly name the alternative or clarify the bulk scope beyond the word 'many'.

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

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

It provides a clear prerequisite workflow: 'Spending/deletion: preview, then owner-approved confirm:true with the same requestId' and a condition: 'Claim live only when status is active.' It does not state when to use this bulk tool versus the single-campaign status update or other sibling tools, leaving some 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 flag destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the description needed to add mechanics — and it does, explaining the preview-then-confirm approval gate and that the requestId must be reused. It does not say what the cancellation actually releases or whether it is recoverable, which keeps it below 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?

Front-loaded with the purpose, followed immediately by the approval workflow — the most important thing an agent needs. The trailing 'Fields: soclo://tools/...' pointer is a low-value artifact but the rest is dense and waste-free.

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

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

For a destructive, nested-parameter tool with no output schema, the description covers the approval gating and idempotency story well but omits the consequence of cancelling (budget release, reversibility) and leaves three parameters undocumented. 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?

The description reinforces the two behaviorally critical parameters (confirm, requestId) beyond their schema text, which is genuinely useful. However, with only 50% schema coverage and a nested parameters object, accountId, platform, and parameters.predictionId are left undocumented in both places, so it does not fully 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 plus resource: 'Cancel reach-frequency booking', which cleanly separates it from the create/reserve/get/estimate siblings in the RF family. It is clear what operation is performed, though it does not name an alternative tool the way a 5 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?

Gives an explicit two-step usage pattern: preview the spending/deletion impact, then re-issue the identical request with owner-approved confirm:true. The precondition 'Claim live only when status is active' further constrains when the call is valid. It stops short of stating when not to use it or which sibling to consult for status 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 flag destructiveHint and openWorldHint, but the description adds valuable specifics: spending/deletion consequences, the confirm gating with matching requestId, and that the claim is only live once status is active. It does not state what happens if confirm is passed without an approved preview or who the 'owner' 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 tight sentences, front-loaded with purpose, then the safety gate, then the completion condition. The final "Fields: soclo://tools/soclo_ads_create_ad_account" clause is a cryptic non-sequitur that adds no information.

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

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

With 10 parameters, a nested payload, no output schema and destructive semantics, the description covers the confirmation workflow well but leaves the bulk of the payload fields and the recovery path (e.g. soclo_ads_operation_status) unexplained. Adequate, but not complete for a creation tool of this complexity.

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

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

Schema coverage is 60% and the nested payload contains many undocumented fields (io, invoice, partner, poNumber, fundingId, mediaAgency, endAdvertiser, invoicingEmails). The description only restates confirm:true and requestId, both already documented in the schema, and the trailing "Fields: soclo://tools/..." pointer conveys no parameter meaning.

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

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

States a specific verb and resource: "Create Meta ad account." An agent can distinguish it from soclo_ads_list_ad_accounts or soclo_ads_update_ad_account without opening the schema. No explicit sibling routing, 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?

Gives a real usage gate: spending/deletion actions require a preview first, then an owner-approved confirm:true reusing the same requestId. However, it never names the preview tool or its sibling, so the agent must still discover how to obtain the preview.

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=false. The description adds meaningful context beyond that: a required preview-then-owner-approval flow, requestId reuse for recovery, and the 'claim live only when status is active' success condition. It doesn't describe payload validation or failure modes, but the added confirmation semantics are substantive.

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 confirmation constraint and success condition are front-loaded and each sentence carries weight. The trailing 'Fields: soclo://tools/...' line is terse to the point of being cryptic and doesn't itself explain anything, a minor inefficiency.

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

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

For a destructive, nested-payload creation tool with no output schema and 60% schema coverage, the description covers the approval workflow but leaves the payload shape and audience-type variations unexplained. Delegating 'Fields' to an external URI leaves a gap an agent must fill from the schema alone.

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

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

Schema coverage is 60%, with descriptions on confirm, requestId, adAccountId, and the expected* fields. The description reinforces confirm/requestId semantics but does nothing for the large nested payload structure or the many audience-type variants, so it doesn't compensate for the coverage gap. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Create custom audience') and scopes it to Soclo Ads, so the action is unambiguous. It does not differentiate from close siblings such as soclo_ads_update_ad_audience or soclo_ads_add_users_to_ad_audience, leaving the agent to infer which variant applies.

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 the confirmation protocol ('preview, then owner-approved confirm:true with the same requestId') which is genuine when-to-use workflow guidance. However, it never says when to create versus update or replace an audience, and offers no alternatives among siblings.

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

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

Beyond the destructive/openWorld/non-idempotent annotations, it discloses that confirmed creation requests active status except Google Performance Max and Demand Gen, which are created paused, and warns not to report an ad as live until active. It also covers requestId retention for ambiguous outcomes, which is exactly the operational detail annotations cannot carry.

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

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

Front-loaded with the core action, then the quote/confirm/recovery instructions in a compact sequence. It is dense but every sentence carries an operational rule; the trailing 'Fields: soclo://...' pointer and the opening restatement of the title are the only low-value lines.

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

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

A destructive, non-idempotent mutation with 10 parameters, nested payload, and no output schema is adequately covered: the quote/confirm contract, requestId recovery, and post-creation status behavior are all stated. The gap is the large payload object's field semantics, which the description defers entirely to the schema.

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

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

With 60% schema description coverage, the description adds real meaning for the two most consequential parameters: confirm's gating semantics and requestId's reuse requirement for confirmation and recovery. It does not explain the payload fields or the expectedBudgetAmount/expectedCurrency approval guards, relying on schema descriptions for those.

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: creating an advertising campaign in a connected ad account with supplied settings. It implicitly separates itself from ad-set/ad-level creators in the sibling list (create_ad_set, create_standalone_ad), but 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?

Explicitly prescribes the two-step flow: quote first by calling without confirm:true, show the spending preview, get owner approval, then confirm with the same requestId. It also names soclo_ads_operation_status as the recovery path for uncertain results and forbids automatic repeat of the purchase, so the when/when-not decision is fully 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 flag destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is known. The description adds genuinely new behavioral context: an approval gate keyed to spending/deletion with a reused requestId, and the post-condition that the catalog is not live until status reads active. It stops short of saying what exactly is spent or what side effects accompany catalog creation.

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 purpose followed by the safety procedure — no padding. The trailing "Fields: soclo://tools/soclo_ads_create_ad_catalog" is cryptic noise whose meaning is not explained, slightly weakening an otherwise tight entry.

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 10-parameter, non-idempotent, destructive, open-world mutation with no output schema, the description covers the approval workflow but leaves the payload contract and the mismatch-prone expected*/budget parameters unexplained, and says nothing about what a successful response returns beyond the status phrase. Annotations carry the safety burden, but the parameter story is 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 coverage is 60%, and the description mostly restates what the schema already documents for confirm and requestId (owner approval, requestId reuse) rather than adding detail. The nested payload fields (name, vertical, businessId, catalogAccountId) and the four expected*/platform parameters are undocumented in either place, so the agent gets no help on the hardest part of 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?

The description opens with a specific verb+resource: "Create a Meta product catalog," which is clearly distinct from sibling catalog tools like create_ad_catalog_feed, create_ad_catalog_product, and create_ad_catalog_product_set. It doesn't explicitly name those siblings to differentiate, but the resource noun is precise enough that an agent can route correctly.

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 lays out a concrete procedural rule: preview first, then owner-approved confirm:true reusing the same requestId, and only treat the entity as live when status is active. That is clear usage guidance for a mutating tool, though it never names which sibling performs the preview or checks status (e.g. soclo_ads_operation_status), leaving the agent to infer the partner tools.

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

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

Annotations already declare non-read-only, destructive, open-world, non-idempotent. The description adds genuinely new behavior: an owner-approval gate, requestId reuse for confirmation and recovery, and the condition that the feed is only 'live' once status is active. It omits what exactly is destructive (spending implications of the feed schedule) beyond the terse 'Spending/deletion' phrase.

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 clauses: purpose, safety workflow, state claim, plus a documentation pointer. Front-loaded with the operation and no filler sentences.

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

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

For a 10-parameter, nested-object, destructive mutation with no output schema, the description covers the approval/confirmation loop and outcome-recovery hint but not the feed schedule structure, required catalog linkage, or what a successful response/status looks like. Adequate but with clear gaps an agent would hit on first 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 60%, and the description reinforces the two most consequential parameters (confirm and requestId) with approval/reuse semantics. It says nothing about the nested payload (name, schedule interval/url/hour/dayOfWeek) or the accountId vs adAccountId vs parameters.catalogId distinction, leaving the remaining 40% of undocumented params unaddressed.

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

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

The description states a specific verb and resource ('Create a product feed') and scopes it to Soclo Ads, so an agent can distinguish it from reads like list_ad_catalog_feeds. It does not, however, explicitly distinguish it from the very close sibling soclo_ads_create_ad_catalog_feed_upload, which an agent would need to disambiguate between.

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 procedural path (preview first, then owner-approved confirm:true with the same requestId) which implies when confirmation is appropriate. But it never names the preview/quote sibling to call first, nor when to choose this over the feed-upload variant, so the routing guidance 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so safety burden is partly covered. The description usefully adds that confirmation requires owner approval with a reused requestId and that success is only claimed at status 'active' – real workflow context – but it never says what is mutated or destroyed, which matters given destructiveHint.

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

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

It is short and front-loads the operation, but the trailing 'Fields: soclo://tools/soclo_ads_create_ad_catalog_feed_upload' sentence adds no information and is a wasted slot. The remaining sentences are terse to the point of fragmentation rather than 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?

For a 10-parameter destructive mutation with nested objects and no output schema, the description omits the source of the feed, which identifiers are needed, budget/currency expectations, and any sense of the result beyond 'status is active'. Only the confirm workflow is covered, leaving the definition substantially 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 coverage is only 60% across 10 parameters including a nested payload object, and the description names no parameter at all. The 'Fields: soclo://tools/...' pointer is a self-reference, not documentation, so nothing compensates for the gaps in url, catalogId/feedId, expectedCurrency and expectedBudget*.

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 ('Fetch a feed file now') restates the title verbatim and never explains the actual operation implied by the name: creating an upload record for an ad catalog feed from a source URL. It doesn't distinguish this from closely-named siblings like soclo_ads_create_ad_catalog_feed or soclo_ads_list_ad_catalog_feed_uploads, so an agent must infer scope.

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 real procedural rule ('preview, then owner-approved confirm:true with the same requestId') that tells the agent how to sequence calls. However, it names no alternative tool and gives no conditions for choosing this over list_ad_catalog_feed_uploads or create_ad_catalog_feed, leaving selection to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety bar is lower. The description still adds real context beyond them: the two-step preview/confirm sequence, requestId reuse for confirmation and recovery, and the 'claim live only when status is active' gating. The spending/deletion phrasing reads like boilerplate cargo-culted from other tools, slightly muddying the message.

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?

Purpose is front-loaded and the text is short, but the bare 'soclo://tools/...' URI does not earn its place, and the 'Spending/deletion' boilerplate is not clearly relevant to adding a catalog product (an add operation), so it risks misdirecting the agent rather than informing it.

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

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

The tool takes a deeply nested payload.product object with ~30 fields and has no output schema, yet the description explains nothing about required product fields, what gets created, or what is returned. For this complexity level the definition is under-specified; an agent would have to lean almost entirely on the raw 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?

At 60% schema coverage, the description's only param-level value is the confirm:true and same-requestId semantics, which genuinely clarify those fields. However, the 'Fields: soclo://tools/...' pointer is a bare URI, not documentation, and it adds nothing about the 30+ nested product fields or catalogId/accountId.

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 title and first sentence give a specific verb+resource ('Add a product to a catalog'), letting an agent distinguish it from soclo_ads_update_ad_catalog_product and soclo_ads_batch_ad_catalog_products. It stops short of explicitly naming those siblings as alternatives, so it stays below a 5.

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

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

The description covers the confirm workflow ('preview, then owner-approved confirm:true with the same requestId'), which implies when the confirm parameter is needed. But it never says when to choose this single-add tool over batch_ad_catalog_products or update variants, so sibling selection 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?

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false; the description adds a gating rule (confirm only after owner-approved preview) and a state-verification rule ("Claim live only when status is active") that are genuinely beyond the annotations. Much of the confirm/requestId wording duplicates schema descriptions, and the trailing "Fields: soclo://tools/..." pointer carries no content, so it stops short of rich disclosure about what gets created or how to recover the outcome.

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?

Purpose is front-loaded in one short clause and the safety workflow follows, so ordering is good. But the sentences are telegraphic ("Spending/deletion: preview, then owner-approved confirm:true") and the final "Fields: soclo://tools/..." reference is a dead link that consumes space without delivering 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?

Ten parameters with nested objects, no output schema, and the semantically central `payload.filter` documented as an untyped object in both schema and description. The description points to an external field reference rather than explaining the filter/name/catalogId structure, leaving the most important input undefined for an agent constructing the 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?

Placeholder for internal consistency; see justification text.

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

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

States a specific verb and resource ("Create a product set"), which is more precise than the bare tool name, but it never differentiates from close siblings such as soclo_ads_create_ad_catalog, soclo_ads_create_ad_catalog_product, or soclo_ads_update_ad_catalog_product_set. An agent knows the object being created but not how it relates to the catalog/product hierarchy.

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 a two-step flow ("preview, then owner-approved confirm:true") and a liveness condition ("Claim live only when status is active"), which gives useful invocation context. It does not, however, name the preview/status sibling tools (e.g. soclo_ads_operation_status) or say when to prefer this over other catalog creation tools, so the routing guidance is implied rather than explicit.

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

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

Annotations already mark this as non-read-only, destructive, and open-world. The description adds meaningful behavioral context beyond annotations by explaining the preview/owner-approval gate, confirm:true requirement, requestId reuse, and the condition that the claim is live only when status is active.

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

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

The description is short and front-loads the purpose. The spending/deletion workflow follows logically, though the final 'Fields: soclo://...' fragment is cryptic and does little work.

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

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

For a destructive, spending-related creation tool with a complex nested payload and no output schema, the approval workflow is covered well. But important call semantics remain under-explained, especially the payload structure, required fields, and what a successful creation returns.

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

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

The schema covers 60% of the 10 parameters, but the description adds little parameter meaning. It mentions confirm and requestId, which are already documented in the schema, and the line 'Fields: soclo://tools/...' is a reference rather than useful explanation of the nested payload or the other undocumented parameters.

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

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

The description states a specific verb and resource: create a standalone creative. It is clear what the tool does, but it does not distinguish this creative-creation tool from nearby siblings such as soclo_ads_create_standalone_ad or soclo_ads_create_call_ad.

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

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

The description gives procedural guidance for spending/deletion actions: preview, obtain owner approval, then call with confirm:true and the same requestId. However, it does not say when to choose this tool over sibling creative or standalone-ad creation tools.

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

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

Annotations already flag destructive=true, non-idempotent, and open-world, so the safety bar is lower. The description adds genuine context beyond them: the operation is async, requires an owner-approved preview before confirm:true, expects requestId reuse for confirmation/recovery, and reports live only at active status. That is meaningful behavioral disclosure of the two-step approval flow.

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

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

The core workflow sentences are tight and front-loaded, but the trailing 'Fields: soclo://tools/...' reference is unexplained and reads as a dangling pointer rather than actionable guidance, detracting from an otherwise compact definition.

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

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

For a destructive, non-idempotent async mutation with no output schema, the description covers the approval/preview and status lifecycle but omits how to poll for completion (e.g., via soclo_ads_operation_status) and what the payload fields control. Adequate but with clear gaps given the tool's complexity.

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

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

Schema coverage is 60%, but the heavy nested 'payload' object (level, fields, datePreset, filtering, breakdowns, timeIncrement, etc.) has no per-field descriptions, and the description only annotates the confirm/requestId workflow while deferring the rest to a cryptic 'Fields: soclo://...' pointer. For a 10-parameter tool with a large undocumented payload, this leaves real ambiguity.

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

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

The description states a clear verb and resource ('Submit async insights report') and ties it to Soclo Ads. However, it does not distinguish this from clearly related siblings like soclo_ads_get_ad_insights_report and soclo_ads_query_ad_insights, leaving the agent to infer the async-submit vs. read 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?

It gives a useful workflow cue ('preview, then owner-approved confirm:true with the same requestId') and a state gate ('Claim live only when status is active'). But it never says when to choose this tool over the get/query insights siblings, so usage context 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 description adds the approval/confirm protocol and requestId reuse semantics that the annotations (destructive=true, idempotent=false, openWorld=true) do not convey, which is genuinely useful. However the 'Spending/deletion' framing is boilerplate that does not match creating a label, and 'Claim live only when status is active' is opaque jargon with no explanation of what status refers to or where to read 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?

Four short sentences, front-loaded with purpose then the operational constraint; nothing is padded. The URI pointer and the 'Spending/deletion' clause are the weakest elements and read as boilerplate.

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 10-parameter, nested-payload mutation with no output schema, the description omits the payload contents and the expectedCurrency/expectedBudget* approval-verification fields entirely. It mentions requestId for outcome recovery but does not point at soclo_ads_operation_status, leaving the recovery path implicit.

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

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

Schema coverage is 60%, so the description need not document everything, but it only reinforces confirm and requestId — both of which already have schema descriptions — and never mentions payload.name, backgroundColor, description, or the expected* approval-verification fields. The 'Fields: soclo://tools/...' pointer is a reference rather than usable meaning.

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

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

States a specific verb and resource ('Create a Google Ads label'), which cleanly separates it from soclo_ads_update_ad_label, soclo_ads_remove_ad_label and soclo_ads_list_ad_labels by name. It does not draw the line against soclo_ads_attach_ad_label (applying an existing label to an entity), which is the one sibling an agent could plausibly confuse it with.

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

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

Gives a concrete precondition sequence: preview first, then owner-approved confirm:true reusing the same requestId, and only treat the result as live once status is active. It does not say when to choose create-label versus attach-label, so the alternative-selection guidance is incomplete.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description adds real value on top: the preview-then-confirm gate, requestId reuse for outcome recovery, and the requirement to confirm only after owner approval of a spending/deletion preview. The 'Spending/deletion' framing is boilerplate that doesn't map cleanly to creating a keyword list, but it does not contradict the destructive annotation.

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 statements with no filler: purpose first, then the confirm workflow, then the liveness claim. The trailing 'Fields: soclo://tools/...' fragment is cryptic and the telegraphic 'Spending/deletion:' prefix costs a little clarity, but nothing is padded.

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

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

For a destructive, 10-parameter tool with nested payload and no output schema, the description covers the approval gating but omits how the preview is obtained (call without confirm?), what a pending/active status looks like, and that soclo_ads_operation_status recovers outcomes. The 'Claim live only when status is active' line gestures at this without making it actionable.

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