Social Media MCP by Publinio

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

Annotations already declare mutation, idempotency, and non-destructive behavior. The description adds meaningful context beyond them: saving does not trigger a paid scan, capabilities should be checked first, and idempotencyKey should be reused on retry.

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 primary action and key distinction. Every sentence carries useful information without repetition.

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

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

The output schema covers return values and annotations cover safety, but for a six-parameter mutation with 0% schema description coverage, the description leaves several parameters unexplained. It is minimally sufficient, not complete.

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

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

Schema description coverage is 0% across six parameters. The description explains idempotencyKey retry behavior and lists platform values, but leaves brandId, url, label, and category semantics undocumented in both the schema and the description.

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

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

States a specific verb ('Save'), resource ('target'), supported platforms, and scope ('for this brand'). The sentence 'Saving does not start a paid scan' distinguishes it from scan_intelligence_target, so an agent can select it without opening the schema.

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

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

Gives a prerequisite ('Check capabilities first') and clarifies that saving is separate from paid scanning. It also advises reusing idempotencyKey on retry. No explicit named alternative for scanning is given, but the context is clear.

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

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

Annotations already flag a non-read-only, non-idempotent, open-world operation, but the description adds real value beyond them: it discloses that the call consumes a scarce 'analysis allowance' and that the output is a creative hypothesis rather than proof of profitability. That quota-consumption and expectation-setting context is exactly what annotations cannot convey.

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

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

Two tight sentences with zero filler, and the leading clause carries the core action while the trailing clause handles the caveat. Nothing is repeated from structured fields.

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

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

Because an output schema exists, return values need not be described, and the hypothesis-vs-proof caveat covers the key output caveat. However, with 0% schema coverage and no usage routing, the definition is only minimally complete for a side-effectful, quota-consuming operation.

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

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

Schema description coverage is 0%, with three required parameters (brandId, adId, idempotencyKey) and no property descriptions. The description alludes to 'a selected public ad' but never explains the required ids or the role of idempotencyKey, so it fails to compensate for the coverage gap.

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

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

States a specific verb (Analyze) and resource (a selected public ad), so an agent can tell it apart from read-only siblings like get_library_ad or search_library_ads. It stops short of naming those alternatives, but the analysis framing is clear.

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

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

The phrase 'using the existing analysis allowance' implies a quota-gated operation, which is useful context, but there is no explicit when-to-use vs. when-not, and no pointer to get_library_ad, get_ad_breakdown, or compare_intelligence as alternative paths. Guidance 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 mutation, destructiveness, and idempotency, so the bar is lower; the description still adds two things the annotations do not: 'App-only' (app-level auth required, not a user session) and the scope limit that it does not activate or publish. It omits whether approval is reversible, which matters given destructiveHint=true.

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

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

Two short sentences with zero filler; the action and its scope are front-loaded and the exclusion trails immediately. 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?

An output schema exists, so return values need not be explained, and the annotations carry the safety profile. What still feels thin is only the parameter semantics given the 0% schema coverage; otherwise the description covers what, scope, auth, and reversibility edge cases adequately for a commit-style tool.

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

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

Schema description coverage is 0% across five required parameters. The description only loosely maps to two of them ('completed sample' -> sampleRunId, 'automation revision' -> revision) and says nothing about brandId, automationId, or the required idempotencyKey, so an agent gets no help on format or role for the majority of inputs.

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

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

The description names a specific verb+resource pair ('Approve the exact completed sample and automation revision') and scopes it to the reviewed revision, which separates it from the other approve_* siblings (approve_campaign, approve_brand_fact) and from control_automation. It could be sharper about what 'approve' commits, but an agent can distinguish it from siblings without opening the schema.

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

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

It states the precondition ('the exact completed sample and automation revision reviewed in the UI') and an explicit exclusion ('does not activate or publish'), which steers the agent away from treating this as an activation call. No sibling tool is named as the alternative for activation, but the boundary is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety traits are covered. The description adds the UI-only availability constraint, which is genuinely new context, but it does not explain what approval destroys (prior revision?) or the concurrency semantics implied by 'exact revision reviewed in the card'.

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

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

Two tight sentences, front-loaded with the action and immediately followed by the availability constraint. No wasted words, though the terseness contributes to the parameter gaps rather than resolving them.

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

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

An output schema exists, so return values need not be detailed. However, for a destructive, idempotency-keyed mutation with four undocumented required parameters, the description is too thin: it omits preconditions, the effect of approval, and error/failure behavior.

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

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

Schema description coverage is 0%, so the description carries the full burden. It hints at the revision parameter's optimistic-lock meaning ('exact ... revision reviewed'), but brandId, factId, and idempotencyKey are undocumented in both schema and description.

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

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

States a specific verb (Approve) and resource (business fact revision), which distinguishes it from approve_campaign and approve_automation_sample. The phrase 'the exact ... revision reviewed in the card' adds scoping detail. It is clear but does not explicitly contrast against the nearest sibling, save_brand_fact.

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

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

The constraint 'Only available to the app UI' is a meaningful when-not signal, but no positive when-to-use guidance or alternative routing (e.g., approve vs. save_brand_fact) is given. Usage is largely implied from the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is largely covered. The description adds genuinely new context — the UI-only availability constraint and the fact that approval is bound to a specific snapshot and does not trigger scheduling/publishing — but it leaves the destructiveHint unexplained (what approval irreversibly commits) and says nothing about retry behavior despite the idempotencyKey parameter.

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

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

Two short sentences, front-loaded with the action and its scope, followed by the two most decision-relevant constraints (no scheduling/publishing, UI-only). No filler and nothing repeated from the schema or annotations.

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

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

It correctly clarifies the mutation's boundaries and availability, and an output schema exists so return values need no explanation. However, with 0% parameter descriptions and a destructive, idempotent mutation, the definition leaves an agent without enough information about the identifiers it must supply or the irreversible nature of the commit.

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

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

Schema description coverage is 0% across four required parameters, so the description carries the full burden. It conveys the meaning of 'snapshot' via 'the exact campaign snapshot reviewed in the card', but brandId, campaignId and especially idempotencyKey (8-128 chars, presumably replay protection) are never explained, leaving most of the parameter set opaque.

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 ('Approve the exact campaign snapshot') with a stated scope ('including content, settings, assets, facts and times') that pins down exactly what approval binds. It also carves itself off from the adjacent siblings schedule_campaign and prepare_campaign by declaring 'Does not schedule or 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?

Gives clear context (approval is tied to the snapshot reviewed in the card) and an explicit negative boundary that routes the agent away from schedule/publish. It stops short of saying when to choose this over prepare_campaign or what must precede it, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds real behavioral detail the annotations cannot express: cancellation is conditional on the post being editable and is refused for publishing or uncertain-delivery posts. The terms 'safely editable' and 'uncertain delivery' are left undefined, which keeps this from a 5.

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

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

Two short sentences, front-loaded with the action and then the guard condition; nothing is wasted. The qualifier 'only while safely editable' overlaps somewhat with the second sentence's exclusion, a minor redundancy.

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

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

An output schema exists, so return values need no explanation, and the annotations cover the safety profile. However, for a destructive mutation with fully undocumented parameters, the description omits idempotency semantics and what error/refusal behavior the agent should expect when the guard rejects the cancel.

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

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

Schema description coverage is 0%, so the description carries the full burden for three parameters. It only gestures at 'the expected post revision' (implying an optimistic-concurrency match against the revision param) and says nothing about postId or the required idempotencyKey, leaving most parameter meaning undocumented.

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

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

States a specific verb (cancel) and resource (the expected post revision), plus a scope constraint (only while safely editable). It is clearly distinguishable from siblings like update_campaign_post or validate_post, though it never names an alternative operation by name.

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

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

Gives both a positive condition ('only while safely editable') and a negative exclusion ('never cancels a post already publishing or with uncertain delivery'), which is more than most definitions offer. It stops short of naming the sibling tool to use instead when cancellation is refused.

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

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

The annotations already flag destructive=true and idempotent=true, and the description adds genuinely useful behavior beyond them: partial work can still incur credits and final usage/refunds only appear after settlement. That cost-and-timing detail is exactly the kind of context annotations cannot carry. It stops short of saying whether cancellation is immediate or whether an in-flight run must finish a step first.

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

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

Two short sentences, front-loaded with the action and followed by the cost caveat; nothing is padded. The opening sentence is arguably too terse to stand alone, which keeps it off a 5.

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

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

An output schema exists, so return values need not be explained, and the annotations cover the safety profile. However, for a destructive, credit-incurring cancellation the description should identify the cancelled resource and say whether the cancellation is final or synchronous; those gaps leave the agent with an incomplete picture.

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

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

Schema description coverage is 0% for all three required parameters (runId, brandId, idempotencyKey), and the description supplies no parameter information at all. The low-coverage rule requires the description to compensate, and it does not, even though brandId/runId scoping and idempotency-key semantics are non-obvious for a destructive 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 says 'Request cancellation' but never names the resource being cancelled. An agent must infer from the tool name that this cancels a research run rather than a post, campaign, or automation, and the sibling list contains cancel_post as a near-neighbor, so the verb+resource pairing is under-specified.

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

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

There is no guidance on when to use this tool versus cancel_post or the control_* siblings, and no stated prerequisites such as requiring a prior start_research run. The agent gets no routing information beyond the name.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context by warning that differing observation times and missing metrics limit the validity of conclusions, which is data-quality information not available in structured fields.

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

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

Two sentences, zero waste. The core action and scope are front-loaded, and the caveat follows compactly.

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 detail is unnecessary, and the description covers the input meaning and the reliability caveat. Only the lack of routing guidance against neighboring intelligence tools keeps it from being fully complete.

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

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

Schema description coverage is 0%, so the description must carry the load. It partly does: it conveys that targetIds refers to two or three tracked sources belonging to the given brand, mapping both parameters to concepts. However, it adds no format, ID-type, or ordering detail beyond the schema.

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

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

States a specific verb (compare) and resource (saved public metrics for two or three tracked sources belonging to this brand), which distinguishes it from live-scan siblings like scan_intelligence_target. It does not name any alternative explicitly, so it falls short of full sibling differentiation.

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

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

The description implies the scenario (comparing tracked sources) but gives no when-to-use guidance, no exclusions, and no pointer to related tools such as list_intelligence_saved or get_intelligence_target. The agent must infer the appropriate context.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, and openWorld=true. The description adds genuinely new behavioral context: that the user drives a provider login/consent flow and that social passwords must never be requested. Idempotency-key reuse partially overlaps idempotentHint but reinforces the correct call pattern.

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

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

Three short sentences, front-loaded with the action and ending with the security constraint and call discipline. No filler or redundancy.

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

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

An output schema exists, so return values need not be described. The flow (provider login/consent) and safety constraint are covered, but the parameter gaps around brandId and platform keep it from being fully complete for a 3-parameter connection tool.

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

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

Schema description coverage is 0%, so the description carries the full burden. It only touches the idempotencyKey ('reuse the idempotency key') and leaves brandId and platform unexplained beyond the self-documenting enum, a notable gap for a tool with three required parameters.

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

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

States a specific verb (connect) and resource (one social platform to an authorized brand), making the operation clear. It does not explicitly name or distinguish itself from siblings like select_channel_accounts or get_channel_connection, so an agent must infer the boundary.

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

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

Provides context that the user completes provider login and consent, which frames when the tool applies. However, it never states when to use this versus alternatives such as select_channel_accounts or get_channel_connection, leaving routing to inference.

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

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

Annotations already declare destructive=true and idempotent=true, but the description adds context the annotations cannot carry: the consent scopes each action consumes, the fact that some actions spend workspace credits, and the dependency on pre-existing sample approval in Publinio. The instruction to reuse the idempotency key reinforces the retry contract beyond the bare idempotentHint flag.

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 verbs and constrained to four dense sentences, each carrying distinct information (purpose, consents/credits, prerequisites, exclusion, idempotency). It is efficient, though the compressed phrasing around 'existing sample approval in Publinio' and the trailing idempotency note make it slightly terser than 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 destructive, consensual mutation with an output schema, the description covers consents, credit side effects, prerequisites, and an explicit negative constraint, so the agent has what it needs to call safely. It omits what a revision mismatch returns and the meaning of brandId/automationId, minor gaps given the output schema and destructive annotation carry the rest.

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

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

Schema description coverage is 0%, so the description must carry the load. It maps the five verbs to the action enum and clarifies revision as the 'expected revision' (implying optimistic-concurrency matching) and the idempotency key's reuse semantics, but brandId and automationId are never explained. Two of five required parameters remain undefined in both schema and description.

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

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

The description names the exact verbs (pause, archive, activate, resume, sample) and the resource (automation), and it differentiates from siblings by explicitly ruling out sample approval, which routes an agent to approve_automation_sample rather than this tool. An agent can select this over prepare_automation, update_automation, or set_automation_delivery 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?

It states prerequisites conditionally per action (activate/resume/sample require automations:run consent; auto delivery requires posts:schedule consent plus prior sample approval), and gives an explicit exclusion ('Never approve a sample through this tool'). This is when-to-use, when-not-to-use, and the required conditions all at once.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety profile is covered. The description adds genuinely non-structured context: resuming 'authorizes recurring spending under its saved caps' and needs the intelligence:run scope. It does not say what happens to an in-flight run when paused, 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?

Two sentences, front-loaded with the action and immediately followed by the consequential side effect. Every clause earns its place with no restatement of the name or title.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, for a 4-parameter mutation with zero schema descriptions, the definition omits any parameter mapping and does not state the effect of pausing on an already-running schedule, leaving meaningful gaps.

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

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

Schema description coverage is 0% across 4 required parameters, so the description must carry the burden and largely does not. The status enum ('active'/'paused') is only obliquely mapped to 'pause or resume', and brandId, scheduleId, and especially idempotencyKey are never explained or tied to the tool's 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 specific verb pair and resource: 'pause or resume a research schedule', which lets an agent distinguish it from siblings like cancel_research, start_research, and save_research_schedule. It is clear but does not explicitly name which sibling to prefer, so it stops short of a 5.

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

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

Usage context is implied rather than stated: the agent can infer this is the toggle for an existing schedule versus cancel_research (terminate) or start_research (initiate). The note that resuming 'requires intelligence:run' is a real precondition, but there is no explicit when-to-use / when-not-to-use guidance or named alternative.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=true, openWorld=true, so the safety profile is covered. The description adds genuinely non-structured behavior: watches are capped by existing plan limits, refreshes are driven by existing platform jobs, and no custom cadence is guaranteed — useful expectations the agent cannot get from annotations. It stops short of stating auth/permission needs.

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

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

Three short sentences, front-loaded with the action and object, no filler. The trailing "Reuse idempotencyKey" is terse to the point of being slightly cryptic, and the cadence caveat could be tighter, but overall the structure is efficient.

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

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

An output schema exists, so return values need not be explained, and the behavioral context around plan limits and refresh cadence is a real addition. However, with five required parameters at 0% schema coverage and no discriminative usage routing, an agent is left under-equipped to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for five required parameters. It only gestures at advertiser selection ("a selected public advertiser") and idempotencyKey reuse; it says nothing about brandId, source (meta/tiktok enum), advertiserId format, or advertiserName, leaving most parameters undocumented.

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

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

States a specific verb+resource ("Create a watch") against a specific object ("a selected public advertiser"), which cleanly separates it from get_ad_watch, delete_ad_watch, and list_ad_watches. It scopes the operation ("within this brand's existing plan limits") but never names the sibling tools it is distinct from.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternative tool is named despite create/get/delete/list_ad_watch siblings existing. "Reuse idempotencyKey" is parameter advice, not usage routing, so the agent must infer context on its own.

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

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

Annotations already declare destructiveHint=false and idempotentHint=true, and the description reinforces this with 'Does not publish or schedule' and 'Reuse idempotencyKey on retry,' adding the actionable retry behavior rather than just restating the hint. It also discloses the pre-connection drafting mode, which annotations cannot convey, though it omits permission/auth requirements.

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

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

Three tight sentences with zero filler, front-loading the primary action, then the alternate mode, then the key behavioral constraints. Every sentence earns its place.

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

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

For an 8-parameter, nested-object, 0%-coverage tool the description does a fair job on intent and safety but is thin on parameter guidance, even though an output schema means return values need not be explained. It leaves the agent without enough detail to populate connectionId versus platform or the settings sub-object.

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

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

Schema description coverage is 0% across 8 parameters including a large nested settings object, so the description carries the burden. It only hints at media IDs and idempotencyKey; brandId, content, connectionId, and the platform-specific settings keys remain entirely undocumented in both schema and description.

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

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

States a specific verb and resource ('Save a reviewable draft') and clarifies a second mode ('or supply platform to draft before connecting'), which is genuinely distinguishing context. It is clear what the tool produces, though it never explicitly names its closest sibling (update_draft) to sharpen the boundary.

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

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

Provides implied guidance via 'Does not publish or schedule' (steering away from schedule_post) and 'Use existing media IDs' (steering toward search_media/import_media first). However, it never names an alternative tool or gives an explicit when-to-use-this-vs-update_draft condition, so usage is only implied.

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

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

Annotations already declare readOnly=false, idempotent=true, and destructive=false, so the safety profile is covered. The description adds the non-publishing/non-scheduling boundary and an epistemic constraint on causal claims, which is genuine extra context, but it says nothing about idempotency behavior, permissions, or what happens to existing data.

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 payload definition, followed by two tight constraints. Every sentence earns its place with no filler.

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

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

An output schema exists so return values needn't be described, and annotations cover the safety profile. Yet for a 7-parameter mutation with 0% schema coverage and nested variants, the description is thin on parameter meaning and idempotency semantics, leaving the definition only adequately complete.

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

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

Schema description coverage is 0%, so the description carries the burden; it explains the semantic core (hypothesis, metric, labeled variants with labels/postIds), which is valuable. But brandId, title, idempotencyKey, and minimumPostsPerVariant are left entirely undocumented in both schema and description, leaving a real gap.

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

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

States a specific verb (save/create) plus the resource and its payload: a hypothesis, success metric and labeled post variants forming an observational content experiment. An agent can distinguish this from get_experiment/list_experiments, though those siblings are not named explicitly.

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

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

"Does not publish or schedule" draws a useful boundary against sibling tools like schedule_post and prepare_campaign, and the attribution caveat constrains downstream reasoning. However there is no explicit statement of when to reach for this tool versus alternatives, so usage is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is fully covered. The description adds a practical retry directive ('Reuse idempotencyKey on retry'), which is genuinely useful even though it restates the idempotency hint; it does not say what is destroyed or whether auth/permissions are required beyond the annotation signal.

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

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

Two short sentences, front-loaded with the action and resource, followed by the single most important operational caveat. No filler.

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

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

An output schema exists, so return values need not be described, and annotations fully cover the destructive/idempotent profile. For a 3-required-param mutation tool the definition is close to sufficient, with the residual gap being the unexplained brandId/watchId semantics and any permission requirements.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, yet it only touches idempotencyKey and tells the agent nothing about brandId or watchId semantics. The schema's uuid pattern for watchId hints at its nature, but the description leaves two of three parameters unexplained.

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

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

States a specific verb ('Remove') and a specific resource ('this brand's selected advertiser watch'), so an agent knows exactly what gets deleted. It does not explicitly distinguish itself from sibling delete tools (delete_intelligence_target, delete_saved_ad) or from create/get/list_ad_watch, but the name and phrasing make the target 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?

No guidance on when to use this versus create_ad_watch, get_ad_watch, or the other delete_* tools, and no prerequisites or exclusions stated. The only operational note is a retry instruction, which is not usage guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description's only addition is retry guidance for the idempotency key, which restates the idempotent hint in operational terms; it says nothing about whether deletion is reversible or what confirmation semantics apply.

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

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

Two short sentences with the operation front-loaded and no filler. It is efficient, though the second sentence is a behavioral note rather than usage context, and the whole definition is arguably under-specified for a destructive tool.

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

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

An output schema exists, so return values needn't be described, and annotations cover the destructive/idempotent profile. However, for a required-parameter destructive delete with zero schema coverage, the description omits any hint of how to obtain a valid itemId/brandId or the consequences of a wrong id, leaving it only minimally complete.

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

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

Schema description coverage is 0% across all three required parameters, so the description carries the full burden. It only touches idempotencyKey (reuse on retry) and gives no meaning to itemId or brandId beyond their names, leaving the agent to infer that itemId must be a previously listed saved item scoped to brandId.

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

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

The description states a specific verb and resource ('Delete the specific saved evidence item') and scopes it to a brand, which separates it from sibling deletes like delete_saved_ad and delete_intelligence_target. It is clear enough to identify the operation, though it never uses the resource name 'intelligence saved item' the agent will see in sibling tools like list_intelligence_saved.

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

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

The only guidance is 'Reuse idempotencyKey on retry.' There is no statement of when to choose this tool over delete_intelligence_target or delete_saved_ad, no precondition such as item ownership or prior listing, and no warning about when deletion is inappropriate.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds genuinely useful retry guidance ('Reuse idempotencyKey on retry'), which operationalizes the idempotent hint. It does not disclose what data is destroyed (tracked history, scan results) or whether removal is reversible, which would be valuable for a destructive operation.

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

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

Two short sentences, zero filler, with the destructive action stated first and the retry guidance second. Every sentence earns its place and nothing is front-loaded poorly.

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

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

An output schema exists, so return values need not be described. For a destructive, non-readOnly tool with complete schema-coverage failure on parameters, the description is adequate but thin: it omits the effect of deletion on downstream artifacts and doesn't clarify how a targetId is obtained (list_intelligence_targets / get_intelligence_target).

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

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

Schema description coverage is 0% across three required parameters, so the description carries the full explanatory burden. It only addresses idempotencyKey (reuse on retry), leaving brandId and targetId entirely undocumented in both schema and description — an agent must infer their meaning from names alone. Partial compensation for a three-parameter gap is insufficient.

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: 'Remove the selected tracked public source from this brand.' This clearly distinguishes it from sibling add_intelligence_target and from the unrelated delete_intelligence_saved, without naming those siblings explicitly. 'Selected tracked public source' is slightly indirect for what the schema calls a target, but the intent 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?

'After the user requests removal' gives an implied trigger condition, suggesting this action should follow explicit user intent rather than autonomous invocation — useful for a destructive tool. However, no alternatives or exclusions are named (e.g., when to use delete_intelligence_saved or get_intelligence_target first to resolve a targetId), so usage is implied rather than spelled out.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety and idempotency profile is covered. The description adds one meaningful piece beyond that: 'Reuse idempotencyKey', telling the agent how to exploit idempotency on retries. It does not state what exactly is destroyed or any permission requirements.

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

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

Two short sentences, front-loaded with the action and scope, with no filler. The idempotency note is terse but earns its place; wording could be marginally clearer.

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

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

An output schema exists, so return values need no explanation, and annotations cover the destructive/idempotent profile. However, for a 3-required-param destructive mutation at 0% schema coverage, the description leaves the brandId/savedId inputs and failure modes unaddressed, making it only minimally adequate.

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

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

Schema description coverage is 0%, so the description carries the parameter burden, yet it only gestures at idempotencyKey ('Reuse idempotencyKey') and never explains brandId or savedId semantics beyond implying them. Two of three required parameters remain undocumented in plain language.

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

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

States a specific verb (remove) and resource (saved ad) and scopes it to 'this brand's inspiration collection', which separates it from read/lookup siblings like list_saved_ads. It does not explicitly contrast with similarly named deletion siblings such as delete_intelligence_saved or delete_ad_watch, so it falls short of full sibling differentiation.

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

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

There is no guidance on when to use this over alternatives (e.g. delete_intelligence_saved), nor any prerequisite or context statement. 'Reuse idempotencyKey' is a retry instruction, not a when-to-use criterion.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds one genuinely useful behavioral fact ('Does not save them'), which clarifies that suggestions are ephemeral. That said, it creates mild tension with readOnlyHint=false and omits anything about external fetch cost, failure modes, or how the existing discovery is invoked.

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

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

Two short sentences with no filler, and the core action is front-loaded ahead of the non-persistence caveat. Efficient, though the phrase 'using existing discovery' is jargon that consumes space without adding clarity.

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

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

An output schema exists, so return values need not be described. But for a tool with four required, undocumented parameters and a non-trivial discovery flow, the description leaves out parameter meaning and any guidance on choosing it over update_brand_profile or get_brand_context.

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?

Four required parameters with 0% schema description coverage, and the description explains none of them. 'Brand website' loosely maps to website and 'brand profile' to brandId, but flowId (a UUID tied to discovery) and name (2-60 chars) are entirely undocumented, leaving the agent to guess their role.

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

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

States a concrete activity: read the brand website and produce brand profile suggestions. The verb+resource are identifiable ('propose brand profile suggestions'), and 'Does not save them' sharpens the scope. However, it doesn't differentiate itself from close siblings like get_brand_context, get_profile, or update_brand_profile, so an agent must still infer the boundary.

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

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

'Does not save them' weakly implies this is a pre-save drafting step whose output would be persisted via update_brand_profile, but no alternative is named and no when/when-not condition is given. Usage is only inferable, not stated.

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

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

The description asserts a read-only profile ('Read ... Does not modify advertising') while the annotation explicitly sets readOnlyHint=false, so the description contradicts the structured behavioral signal an agent would otherwise trust. It also says nothing about the 'fresh' parameter's refresh behavior, rate limits, or whether results are cached, leaving the side-effect profile actively misleading rather than merely incomplete.

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

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

Two short sentences, front-loaded with the verb and resource, with no filler. The second sentence is arguably a waste since it restates the read-only claim already (incorrectly) implied by 'Read' and adds no new information.

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

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

Because an output schema exists, return-value documentation is not needed, but for a six-parameter tool with one required enum and zero schema descriptions the description is far too thin. An agent cannot infer valid dimension semantics, date-range rules, account limits, or the effect of 'fresh' from what is provided.

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

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

Schema description coverage is 0% across six parameters, so the description must carry the semantics and largely does not. It gestures at accountIds ('selected ad accounts') and since/until ('completed dates') but never explains the required 'dimension' enum values, the meaning/units of the breakdown, or what 'fresh' toggles.

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 concrete verb and resource ('Read a Meta advertising breakdown') and scopes it to ad accounts and completed dates, which is specific enough to separate it from generic reads like get_analytics. However, it never names the closest siblings (get_ad_performance, get_ad_campaign) or states how a 'breakdown' differs from them, so differentiation relies on the enum in the schema rather than the prose.

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

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

There is no when-to-use guidance: no statement of when a breakdown is preferable to get_ad_performance or get_analytics, no prerequisites, and no exclusions. The only usage-shaped hint is the phrase 'completed dates', which obliquely implies that in-flight dates are not usable but never says so outright.

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 carry the safety profile (destructiveHint=false, idempotentHint=true, openWorldHint=false), and the description adds a useful scope clarification, 'Does not modify advertising'. It does not explain the readOnlyHint=false posture or what the 'fresh' flag triggers, so it adds modest context beyond the structured fields.

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

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

Two tight sentences with the core purpose front-loaded and the non-modifying caveat last. No filler; every clause carries information, though the second sentence slightly overlaps the destructiveHint=false annotation.

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

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

An output schema exists, so return values need no explanation, and the description covers the basic contract of a structural read over a date range. Gaps remain in usage guidance and the undocumented 'fresh' parameter, so it is adequate but not complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, yet it only implicitly covers since/until ('explicit reporting period') and campaignId ('campaign'). brandId and the 'fresh' boolean are entirely undocumented in both schema and description, leaving a real gap.

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

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

States a specific verb ('Read') and resource ('Meta advertising campaign, ad sets and ads') scoped to a reporting period, so an agent can distinguish it from a generic campaign read like get_campaign. However, it does not explicitly name the sibling ad tools (get_ad_performance, get_ad_breakdown) it sits beside, so differentiation is left partly to inference.

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

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

There is no when-to-use guidance and no alternative is named, despite a dense set of sibling ad tools (get_ad_performance, get_ad_breakdown, get_ad_watch, get_campaign). Nothing tells the agent when this structural read is preferred over a performance read.

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 frames the tool as a read ('Read ... performance', 'Does not create ads or change budgets'), but annotations declare readOnlyHint=false, directly contradicting that framing. Though the text adds useful traits (currency preservation, reporting periods, freshness, missing metrics), the safety-signal conflict is a serious inconsistency.

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 operation and scope, then behavioral guarantees. No filler or repetition; every clause carries information.

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

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

An output schema exists, so return values need not be described. However, with 7 undocumented parameters and an annotation conflict, the definition is only partially sufficient for an agent to invoke it confidently.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the semantic load. It hints at provider (Meta/Pinterest), date range ('completed dates'), and the fresh flag ('freshness'), but brandId, accountId, and connectionId are entirely unexplained, leaving most parameters ambiguous.

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

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

States a specific verb+resource ('Read ... advertising performance') and pins the providers (Meta, Pinterest) and scope (completed dates). It is largely distinguishable from ad siblings like get_ad_breakdown, though it never explicitly contrasts itself with them.

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

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

Gives negative guidance ('Does not create ads or change budgets') and an implicit timing constraint ('completed dates'), which helps set expectations. It does not say when to choose this over get_ad_breakdown, get_channel_report, or get_analytics, so alternatives remain unaddressed.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely new behavioral context: data is cached, a last refresh time is returned, and crucially no ad-library refresh side effect occurs — information the annotations do not convey.

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

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

Two short sentences, zero waste, with the core purpose front-loaded and the non-obvious no-refresh guarantee second. Nothing could be removed without losing signal.

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

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

With a rich output schema and full annotation coverage, return values and safety are well covered, and the caching/no-refresh behavior is spelled out. The only real gap is parameter-level detail, which is thin given 0% schema coverage.

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

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

Schema description coverage is 0%, so neither brandId nor watchId is documented in the schema, and the description does not compensate — it only alludes obliquely to 'watch' and 'brand'. An agent gets no format, constraint, or lookup guidance beyond the raw types.

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 (Read), resource (cached ads for a watch), and scope (belonging to this brand). This clearly distinguishes it from siblings like list_ad_watches, create_ad_watch, get_library_ad, and search_library_ads without needing to open any schema.

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

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

The phrase 'never triggers an ad-library refresh' implicitly signals when to prefer this tool over refresh-triggering alternatives, but no sibling is named and there is no explicit when-to-use/when-not-to-use statement. Usage must be inferred from the caching note.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real value beyond them: 'Missing metrics are unknown, not zero' clarifies data semantics and 'does not trigger paid refreshes' discloses a cost side-effect neither annotations nor schema mention.

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, each earning its place: the core action, the data-semantics caveat, and the sibling routing. Front-loaded with the main verb and no filler.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. However, with 0% parameter documentation and a listed sibling (get_analytics_summary) left unaddressed, the definition is not fully complete for correct invocation.

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

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

Schema description coverage is 0% across three parameters (brandId, limit, cursor), so the description carries the full burden of explaining them. It says nothing about pagination via limit/cursor or the brandId identity requirement, leaving an agent to infer input behavior entirely from bare JSON types.

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 ('Read stored content metrics') and adds a scope qualifier ('stored', 'captured_at timestamps') that separates it from live/fresh data. It does not, however, distinguish itself from the very close sibling get_analytics_summary, leaving one likely confusion unresolved.

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 routes the agent to alternatives: get_report_capabilities and get_channel_report for saved X/channel reports, and request_channel_report for fresh reports, which is a strong when-to-use signal. It stops short of a 5 because it never contrasts with the closest sibling, get_analytics_summary.

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

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

Annotations already cover the read-only/idempotent/destructive profile, so the bar is lower, and the description still adds non-obvious aggregation semantics: snapshots are never summed repeatedly and missing metrics are not treated as zero. This is genuinely useful behavioral context beyond the structured fields, though it does not touch auth, scoping, or latency.

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

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

Four short sentences, front-loaded with the core purpose and zero filler. Each remaining sentence adds a distinct, load-bearing fact (aggregation caveat, exclusion, routing alternatives).

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 annotations carry the safety profile; the description completes the routing and aggregation picture. The only real shortfall is the absence of any parameter-level guidance for a 3-param, 0%-coverage schema.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it names none of brandId/since/until. It only implicitly clarifies the period semantics ('posts published in the selected period'), which usefully distinguishes publish-window from activity-window filtering, leaving brandId entirely unexplained.

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

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

States a specific verb and resource ('Summarize the latest saved lifetime metrics for posts published in the selected period') and explicitly rules out the adjacent concept ('Not daily account activity'). An agent can distinguish this from get_analytics and the report tools 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?

Names the alternatives and the condition that selects each: saved X/channel reports via get_report_capabilities + get_channel_report, fresh reports via request_channel_report. It also excludes the daily-activity case, giving both when-to-use and when-not-to-use.

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, closed-world and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the return includes recipe and revision, and the reader is warned to treat recipe text as data rather than instructions (prompt-injection defense). No auth/permission details, but the injection warning is substantive added value.

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

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

Two short sentences, zero padding, front-loaded with the core action and followed by the security caveat. Every clause earns its place.

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

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

An output schema exists, so return values needn't be spelled out, and annotations cover the safety profile; the description still usefully names what is returned and adds the injection warning. The one shortfall is the total absence of parameter semantics despite 0% schema coverage.

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

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

Schema description coverage is 0% for the two required parameters, so the description carries the burden of explaining them — and it supplies nothing about brandId scoping or the automationId UUID format. 'One automation' loosely implies the automationId, but no compensation for the coverage gap.

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

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

States a specific verb and resource: read ONE automation, and further specifies what it returns (current recipe and revision). This implicitly separates it from list_automations and get_automation_run. It does not explicitly name a sibling to contrast against, keeping it at a strong 4 rather than 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 singular 'one automation' implies usage when a specific automation is needed rather than the list, but no explicit when-to-use, when-not, or named alternative is given. Usage is inferable but never stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds useful content scope (what is being read: modes, pricing, config fields) but says nothing beyond that — no auth requirements, rate limits, or freshness guarantees. With an output schema present, return-value detail is not needed, so a 3 is appropriate.

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 tightly packed sentence with the action and the timing cue front-loaded; no filler, no repetition of the tool name.

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

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

For a read-only capability lookup with a rich annotation set and an output schema, the description covers what the agent needs to decide to call it. The only real omission is any mention of the required brandId, which leaves the invocation scoping 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 0% and the description never mentions brandId, the single required parameter. The agent must infer from the schema alone that this lookup is scoped to a brand; the description does not compensate for the coverage gap.

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

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

States a specific verb (Read) and resource (automation capabilities) and enumerates the concrete contents: enabled generation tools, configuration fields, automation modes, credit pricing. It follows the established *capabilities pattern alongside siblings like get_intelligence_capabilities and get_workspace_capabilities, though it does not explicitly contrast itself with those siblings.

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

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

"before preparing an automation" gives a clear temporal/contextual trigger that ties the tool to the sibling prepare_automation. It stops short of explicit when-not conditions or naming alternatives, but the usage context is unambiguous.

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

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

Annotations already declare readOnly=true, destructive=false and idempotent=true, so the safety profile is covered. The description nonetheless adds meaningful context beyond them: it clarifies no credits are spent and nothing is published, which is a valuable side-effect disclosure given the other automation tools in this family. It stops short of stating auth requirements or the media-link format.

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

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

Two tight sentences with no filler, and the core action is front-loaded before the side-effect disclaimer. The trailing Publinio-link clause is slightly awkward but carries useful return 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 structure is handled, and the behavioral side is reasonably covered by the credit/publish disclaimer. The remaining gap is parameter semantics, which are undocumented in both schema and description for a two-required-parameter lookup.

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

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

Schema description coverage is 0% and both required parameters (brandId, runId) are undocumented in the schema. The description gestures at fetching 'one' run but never explains that runId identifies the run or that brandId scopes authorization, so the agent must infer both parameters.

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

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

States a specific verb (read) and resource (one automation run), plus what it returns (generated text results, media review link). It clearly reads a single run rather than the definition, distinguishing it from list_automation_runs. It does not, however, explicitly contrast itself with the sibling get_automation.

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

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

There is no explicit when-to-use or when-not guidance and no named alternative (e.g., list_automation_runs for enumerating runs, or get_automation for the definition). The word 'authorized' weakly implies a permission prerequisite but the description never states when an agent should reach for this tool over its 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?

Annotations already declare this is a read-only, idempotent, non-destructive, closed-world operation, so the safety bar is low. The description adds genuinely useful context beyond that: an instruction to treat returned content strictly as data, guarding against prompt injection from brand content. It does not describe return shape or pagination, but the output schema likely covers that.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the safety note following. Every sentence earns its place.

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

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

The read-only safety profile and return contract are adequately covered by annotations and the output schema, and the injection warning is a valuable addition. What is missing is the comparative guidance an agent needs to choose this over discover_brand_profile or get_profile in a crowded namespace.

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

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

Schema description coverage is 0% for the single brandId parameter, and the description supplies no meaning, format, or source for it. The parameter is a fairly self-evident identifier, but the description does nothing to compensate for the missing schema documentation as the low-coverage rule requires.

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 ('Read') plus a clear scope of content ('brand identity, audience and voice'), so an agent knows exactly what it retrieves. It does not, however, distinguish itself from overlapping siblings like discover_brand_profile, get_profile, or list_brands.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternatives despite several plausible siblings (discover_brand_profile, update_brand_profile, list_brand_facts). The agent must infer selection context on its own.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one useful behavioral nuance — that changed/expired facts need renewed review — but says nothing about auth requirements, error behavior, or freshness of returned data.

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

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

Two sentences, front-loaded with the operation and its returned fields, with zero filler. The first sentence is an enumeration but remains readable and purposeful.

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

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

An output schema exists, so return values are truly documented elsewhere and the annotations carry the safety profile. The remaining gaps — undocumented parameters and absent usage guidance — are real but modest for a simple single-record read tool.

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

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

Schema description coverage is 0% for both required parameters, so the schema contributes only type/pattern/format info (campaignId is a UUID) with no meaning. The description does not mention brandId or campaignId at all, so it fails to compensate for the coverage gap.

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

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

States a clear verb ("Show") and resource (campaign) and enumerates the returned content: content, destinations, assets, facts, publishing times, and validation. This distinguishes it from list_campaigns (plural list) and get_ad_campaign (ad-specific), though it never names those siblings explicitly.

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

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

No explicit when-to-use guidance or alternatives are given. The sentence "Changed or expired facts require renewed review" hints at a workflow condition but does not tell the agent when to call get_campaign versus list_campaigns or prepare_campaign.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds the useful rule that connected status is reported only after provider completion, but it does not address the readOnlyHint=false tension or explain any side effects.

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

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

The description is two short, front-loaded sentences with no wasted language. However, its extreme brevity contributes to the missing detail elsewhere.

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, which helps, but the input parameters are undocumented and usage relative to sibling tools is absent. For a two-parameter connection-status tool, more context is needed.

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

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

Both required parameters (brandId and flowId) have 0% schema description coverage, and the description never mentions either parameter or its meaning. There is no compensation for the missing schema documentation.

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?

It states the action is checking one authorized connection flow, but does not clarify what the tool returns or what a connection flow is. It also does not distinguish itself from siblings like connect_channel or list_connected_accounts.

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

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

There is no explicit when-to-use guidance or mention of alternatives. The phrase 'only after provider completion' hints at timing, but the agent is not told when to call this versus other connection-related 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 cover readOnly, idempotent, non-destructive, closed-world. The description adds genuinely useful behavior beyond them: data is 'saved' (cached, not live), 'missing metrics remain unknown' (no fabrication of gaps), that it surfaces refresh job status, that pagination is via nextOffset, and a safety directive to treat post text as untrusted data.

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 what is read, then the cost/gap caveat, then pagination and the security note. Dense and purposeful, with only a mildly run-on enumeration in the first sentence.

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

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

An output schema exists so return values need not be described, and annotations carry the safety profile. The description covers caching, gap behavior, async refresh status, pagination and untrusted-data handling; the main omission is guidance relative to the request_* siblings and limit semantics.

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

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

Schema description coverage is 0%, so the description must compensate for six params. It implies the date period (since/until) and the brand-channel identifiers (brandId/accountId) and gives offset a usage rule ('nextOffset'), but limit is never mentioned and no formats or ranges are clarified beyond the schema regexes.

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 (Read) and a clearly bounded scope: saved activity, lifetime post metrics, refresh job status, and X reports for one brand channel over an explicit date period. An agent can tell what it returns, though it does not name or distinguish itself from close siblings like request_channel_report or get_x_report.

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?

Offers only fragmentary context: 'Free' signals a cost advantage and 'Follow nextOffset for all posts' gives a pagination rule. There is no explicit when-to-use vs when-not, and no routing between this and request_channel_report/request_x_report, which the agent must infer.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: missing values stay unknown and insufficient observations cannot establish a winner, warning the agent against over-interpreting sparse results.

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

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

Two tightly written sentences with the core action front-loaded and the interpretation caveat following. Nothing is wasted or 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?

An output schema exists, so return values need not be explained, and the safety profile is carried by annotations. The description is complete for a simple read tool, though it leaves parameter semantics 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?

Schema description coverage is 0% for two required parameters, so the burden falls on the description, which mentions neither brandId nor experimentId. The parameter names are largely self-explanatory, but the description contributes no added meaning (e.g., which brand the experiment is scoped to).

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: compares latest stored metrics for a saved experiment, and specifies the scope includes coverage and timestamps. It reads clearly as distinct from list_experiments, but never explicitly names or differentiates itself from its siblings.

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

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

The description gives no when-to-use guidance, no prerequisites, and does not point to alternative tools such as list_experiments or compare_intelligence. The second sentence is interpretive framing about results, not usage direction.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world). The description adds real value beyond them by disclosing that availability is volatile and platform access is not guaranteed, which tells the agent to re-query rather than cache. It stops short of saying whether the credit price can change per scan or how it is surfaced.

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

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

Two tight sentences with the actionable content (what is checked) front-loaded and the caution second. No filler; slightly more compact than necessary but well structured.

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

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

For a read-only capability query with an output schema present, the description need not explain return values, and it correctly focuses on what is checked and when to call it. The only substantive gap is the unaddressed brandId scoping and the ambiguity versus the other *capabilities siblings.

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

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

Schema description coverage is 0% for the single required brandId parameter, and the description never mentions it. The rubric requires the description to compensate when coverage is below 50%, and it does not; the agent must infer that the capability check is brand-scoped from the schema name alone.

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

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

The description names the specific resource being checked and enumerates the concrete payload: source availability, public ad library allowances, and the current scan credit price. That is enough for an agent to know this is a capability/pricing lookup rather than a listing or mutation. It does not, however, distinguish itself from the three sibling capability tools (get_automation_capabilities, get_report_capabilities, get_workspace_capabilities).

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 researching" gives a clear timing cue, which is genuine usage guidance. But there is no explicit when-not and no differentiation from the sibling capability-lookup tools, so an agent facing four *capabilities tools must infer which one fits.

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

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

Annotations already establish readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely new behavioral context beyond that: this is a polling endpoint meant to be called repeatedly after a scan request, which tells the agent repeated invocation is expected and no side effects result from polling.

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

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

Two tight sentences, zero filler, with the core action front-loaded and the polling caveat immediately after. Nothing should be cut.

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

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

An output schema exists, so return values (status and saved brief) need no elaboration, and the polling workflow is stated. The remaining gap is parameter provenance, which an agent may have to infer from the scan-request 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?

Schema description coverage is 0% for both required parameters. 'For this brand' loosely hints at brandId, but the description never explains scanId, its UUID form, or that it comes from the scan request response — the one piece of information an agent most needs to call this correctly.

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 (read a scan status and saved brief) with scope ('for this brand'), which is clear enough to distinguish from sibling listing tools like list_intelligence_saved or get_intelligence_target. It also implicitly separates itself from the scan-starting sibling by warning against starting a scan just to check status.

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

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

Gives explicit timing guidance ('Poll this after requesting a scan') and an explicit anti-pattern ('never start a new scan merely to check status'), which routes the agent away from scan_intelligence_target for status checks. It does not name the sibling tool by name or state preconditions such as how long a scan takes to complete.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new context: cursor-based paging, the data-quality caveat that missing metrics mean unknown rather than zero, and the guarantee that the source is not re-fetched. It stops short of stating result size limits or auth requirements.

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

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

Three terse sentences, front-loaded with the core read semantics, with the pagination and data-quality caveats packed into a single clause each. No filler or restatement of the name.

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

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

With an output schema present, return-shape explanation is unnecessary, and the description covers the read contract, paging, staleness behavior, and a meaningful data caveat. The main omission is any parameter guidance for the six undocumented optional inputs, which matters for a tool with this many knobs.

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

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

Schema description coverage is 0% across 8 parameters, so the description must carry the load. It only touches pagination (nextCursor) and says nothing about days, sort, limit, scanId, search, or how brandId/targetId scope the read. The enums and defaults in the schema are self-documenting, which softens the gap slightly but does not fill it.

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

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

Names a specific verb (Read) and resource (a tracked source's saved content, metrics and brief), which is far more precise than the sibling list_intelligence_targets. The closing clause 'Does not refresh the source' implicitly separates it from scan_intelligence_target, but no sibling is named outright, so an agent must still infer the boundary.

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?

'Follow nextCursor' gives a concrete procedural cue for continuing, and 'does not refresh the source' hints that a scan tool is the alternative when fresh data is needed. However, no explicit when-to-use/when-not or named alternative is stated, so usage is only implied.

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

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

The description explains why readOnlyHint is false: reading may 'refresh TikTok details if stale', which is a write to cached state and is genuinely additive beyond the annotations. It also discloses a data-validity limitation (public targeting data cannot establish effectiveness or sensitive traits). It does not cover auth requirements or refresh frequency bounds, so it falls short of 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 short sentences, no filler, with the core action and its side effect front-loaded. The caveat sentence earns its place by warning the agent against over-interpreting the returned targeting data.

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

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

An output schema exists, so return values need no explanation, and the refresh behavior plus data caveat are covered. However, the two required identifiers are undocumented and there is no routing guidance against analyze_library_ad or search_library_ads, leaving real gaps for a tool with 0% schema description coverage.

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

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

Schema description coverage is 0% for two required parameters, so the description must compensate and does not. brandId and adId are never explained, and the UUID/pattern constraints in the schema carry no human-readable meaning. 'Public ad' only loosely implies what adId identifies.

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 and resource: 'Read a saved public ad', plus the side effect of refreshing stale TikTok details. That distinguishes it from save_library_ad and delete_saved_ad, but it never contrasts itself with the close sibling analyze_library_ad, which also operates on a library 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?

No when-to-use guidance and no alternatives named. It never says to prefer analyze_library_ad for evaluation or search_library_ads to locate an ad first. The only usable cue is the implied 'requires an already-saved ad' from the phrase 'saved public ad'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds a little context by saying the read includes revision, approval and publishing status, but it discloses nothing about errors, missing posts, or permission requirements.

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

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

One short sentence, front-loaded with the verb and resource, with the scope qualifier immediately after. Nothing is redundant or padded.

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

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

An output schema exists, so return-value documentation is unnecessary, and annotations cover the behavioral profile. For a single-parameter read tool the description is close to sufficient, with only the parameter's origin/format left unaddressed.

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

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

Schema description coverage is 0% and the description never mentions the postId parameter, its UUID format, or where to obtain it. The single required parameter is self-evident from its name, so the gap is minor rather than damaging, landing at the baseline.

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

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

States a specific verb ('Read') and resource ('post') and scopes the payload to the current revision plus approval and publishing status, which separates it from list_posts and the various get_campaign/get_ad_* readers. It does not explicitly name a sibling it is not, so it stops short of the top of the scale.

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

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

There is no when-to-use guidance, no stated prerequisites, and no alternative named (e.g. list_posts for discovery vs get_post for a known ID). Usage is only inferable from the verb.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety and stability profile is covered. The description adds one real piece of context beyond that: the returned identity is 'opaque' (not a human-readable PII value like an email), which tells the agent not to expect usable profile fields. Still thin on what the caller actually receives.

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

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

Two short sentences, front-loaded with the action and result, with the 'no email required' qualifier placed immediately after. Nothing is padded or 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?

An output schema exists, so return-value detail need not be in the description, and a no-arg read tool is inherently simple. The description is close to sufficient, though a one-clause note on when to prefer it over the brand/workspace context tools would make routing unambiguous.

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 schema carries no semantic burden and the baseline for a no-param tool applies. Nothing in the description is needed to explain parameter usage.

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 ('Return a stable opaque identity for this authenticated account'), which is clearly distinct from a profile-mutation tool like update_brand_profile. However, with ~65 siblings including discover_brand_profile, get_brand_context, and get_workspace_capabilities, it never explicitly distinguishes itself from those identity/profile-adjacent tools.

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

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

The phrase 'No email required' implies the useful context that this is the cheap identity lookup that avoids an email-based flow, but there is no explicit when-to-use, when-not, or named alternative (e.g., discover_brand_profile). Usage is only implied.

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

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

Annotations already establish readOnly, idempotent, and non-destructive. The description adds the two facts annotations cannot express: the call is free (no credit spend) and it never triggers work. Per-channel scope is also disclosed. Return shape is left to the output schema, which exists.

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

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

Three short sentences, front-loaded with the returned data set, then cost/side-effect, then the usage trigger. Every clause carries information an agent needs.

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

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

Purpose, cost, side-effect profile, and call ordering are all covered, and return values are handled by the output schema. The only material gap is the undocumented brandId parameter.

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

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

The single parameter brandId has 0% schema description coverage, and the description never explains what it is or how it scopes the result beyond the vague phrase 'for every connected channel.' With coverage this low the description is required to compensate and does not.

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

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

States a specific verb ('Check') and enumerates the exact resource set it returns: reporting support, saved X reports, credit prices, refresh permission. Ambiguity against siblings like request_x_report is eliminated by the explicit 'never starts work' qualifier.

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?

'Read this before requesting fresh reports' is an explicit when-to-use rule that routes the agent to this tool ahead of the request_* siblings. No exclusion or prerequisite 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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real context beyond them: the default lightweight-while-active vs full-once-settled payload behavior, provisional charges, and a trust warning that evidence is untrusted reference data. This is substantive behavioral disclosure, not a restatement of the 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?

Dense but front-loaded: purpose first, then default payload behavior, then parameter semantics, then operational notes. Each sentence carries distinct information, though the Publinio/alerts sentence is the least load-bearing and borders on extraneous.

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

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

An output schema exists so return values needn't be explained, yet the description still covers the default payload shape, polling cadence, credit settlement timing, and data-trust posture. For a three-parameter read tool this is well-rounded, with only the two identifier parameters unaddressed.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains includeEvidence well (false omits evidence, true loads current observations), but brandId and runId are left to the self-evident schema names/patterns. Two of three parameters get no semantic enrichment, so this lands at the baseline rather than above it.

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

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

States a precise verb and resource ('Read one brand-scoped research run') plus what it surfaces (source progress, credit settlement). The scope word 'one' cleanly separates it from the sibling list_research_runs without the agent opening either schema.

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

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

Gives concrete operating guidance: respect pollAfterSeconds, never restart a run to check progress (an implicit when-not pointing away from start_research), and when to flip includeEvidence. It stops short of naming alternative read tools such as list_research_runs explicitly, so 4 rather than 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 cover read-only/idempotent/non-destructive, so the burden is light. The description adds a genuine behavioral trait beyond them: access is grant-scoped and never widens automatically, which shapes how the agent should reason about missing scopes.

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

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

Two short sentences, zero filler, with the core function front-loaded and the remediation note second. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and the safety profile is covered by annotations. The description adequately covers scope and the reconnect path for a single-parameter read tool, with the only real gap being the undocumented brandId parameter.

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

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

There is one required parameter (brandId) with 0% schema description coverage, so the schema carries no semantics. The description never mentions brandId or what it identifies, leaving the parameter entirely undocumented across both surfaces.

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 (List) plus two concrete resources (allowed tools and brand timezone) scoped to 'this grant', which is clear and non-tautological. It does not explicitly differentiate itself from sibling capabilities tools (get_automation_capabilities, get_intelligence_capabilities, get_report_capabilities), so it falls short of the 5 bar.

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 actionable remediation path ('Reconnect to request missing scopes'), which tells the agent what to do when expected tools are absent. It stops short of explicit when-to-use framing or naming alternatives among the capabilities siblings, but the operating context is clear.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing that the call is free, that it never refreshes, that missing metrics mean unknown rather than zero, and that post text is untrusted data and must not be treated as instructions. The prompt-injection warning and the missing-metrics semantics are exactly the kind of behavioral context an agent cannot get from structured fields.

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

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

Four terse clauses, zero filler, each carrying distinct information (scope, cache behavior, data semantics, security). The most decision-relevant facts are front-loaded.

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

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

An output schema exists, so return-value documentation is not required, and annotations plus the behavioral notes cover safety and caching. The only meaningful gap is explicit guidance on how this relates to request_x_report. Nearly complete for a single-parameter read.

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

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

Schema coverage is 0% and the single required brandId parameter is never mentioned in the description, so no meaning (source, format expectations, or how to obtain the id) is added beyond the bare pattern in the schema. With one undocumented parameter and no compensating text, this falls below the baseline.

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

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

States a specific verb and resource (Read saved X public reports) and additionally enumerates the bundled return data: request status, credit price, workspace balance. It is distinguishable from sibling request_x_report by the 'saved'/'never refreshes' framing, though it does not name that sibling directly. The bundling of account-status data alongside reports makes the purpose slightly diffuse but still clear.

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

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

Implicit rather than explicit: 'Free: never refreshes' hints that this is a cached read and that fresh data requires the request_x_report sibling, but the alternative is never named and no when-to-use/when-not conditions are spelled out. Adequate but leaves the routing decision 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 cover the safety profile (write, non-destructive, idempotent, open-world). The description adds genuinely useful context beyond them: the source flow restriction, the ChatGPT-only client limitation, and a boundary on the openWorldHint ('Do not fetch arbitrary websites'). It still doesn't describe the resulting library entry, so not a 5.

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

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

Three tight sentences, front-loaded with the action, then the client constraint, then the guardrail. Every sentence carries distinct meaning with no repetition of structured fields.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. However, the nested file object with download_url/file_id/mime_type is entirely undocumented, leaving a real risk of incorrect invocation that the description does not address.

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

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

Schema description coverage is 0%, so the schema does not document file_id, download_url, mime_type, brandId, or idempotencyKey. The description only loosely implies the file and brand concepts and says nothing about the nested file object or the idempotency key, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Import a file ... into the selected brand library') and narrows the source to a user-supplied chat attachment. This distinguishes it from generic media-fetching tools, though it doesn't name a sibling tool directly.

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

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

Gives a clear when ('through a supported chat attachment flow', 'currently supports ChatGPT'), a when-not ('Do not fetch arbitrary websites'), and mentions alternatives for other clients ('existing brand media or upload in Publinio'). The alternatives are product features rather than named sibling tools, so it falls 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?

The description adds real behavioral context beyond the annotations: ad access is not implied by a social connection, and a reconnect status is surfaced when provider consent is missing. However, it reads as a pure read ('List ... Returns') while annotations declare readOnlyHint=false, and it never explains what non-read-only side effect that flag reflects (e.g., consent/token refresh), leaving a gap the agent cannot resolve.

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 purpose and followed by the caveat and the return behavior. No filler, nothing repeated from the name 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?

Adequate for a small list tool that has an output schema (so return shape needn't be described, and the mention of reconnect status is a bonus). But with three parameters at 0% schema description coverage, the description leaves the connectionId parameter and the brand-vs-connection scoping unexplained.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and largely does not. It effectively documents the provider enum values ('Meta or Pinterest') and gestures at brandId ('this brand connection'), but says nothing about what connectionId does, that it is optional, or how it narrows the result set versus brandId.

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

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

States a specific verb and resource ('List ... ad accounts') scoped to a brand connection and two named providers. The sentence 'Social connections alone do not imply ad access' implicitly separates it from the sibling list_connected_accounts, though it never names that 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: call it to discover ad accounts reachable through a brand connection for Meta or Pinterest. There is no explicit when-to-use statement, no alternative tool named, and no note on prerequisites such as needing a completed OAuth consent beyond the passing hint about missing consent.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds non-obvious behavioral context beyond the annotations: it explicitly states that reading does NOT trigger a provider refresh, which is exactly the kind of operation-scope detail an agent needs.

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

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

Two tight sentences, zero filler. The primary purpose is front-loaded and the refresh caveat follows immediately. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the key non-obvious fact (no refresh triggered) and what's listed. Adequate for a simple one-parameter list tool, though a brief note on ordering or pagination would fully close 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 0% for the single brandId parameter, but the single required parameter is largely self-describing. The phrase 'this brand's' implies brandId scopes results to a brand, adding marginal meaning, but no format or scoping detail beyond what the schema name conveys.

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 ('Read this brand's saved advertiser watches') plus an extra data element ('last refresh timestamps'), so the agent knows exactly what this returns. It implicitly distinguishes from create_ad_watch/delete_ad_watch, though it doesn't explicitly contrast with the singular get_ad_watch sibling.

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