AdsAgent — Meta Ads MCP

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that it reads the 'authenticated' profile, which is useful context but does not go into additional behavioral details like return format or authorization requirements. With annotations present, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence with no wasted words. It communicates the action, the resource, and the purpose efficiently.

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

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

Given the tool's simplicity (no parameters, read-only, and an output schema exists), the description is complete. The purpose is stated, and the output schema covers return values, so nothing essential is missing.

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

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

The tool has zero parameters, so the description does not need to explain parameter semantics. Per the rubric, 0 params warrants a baseline of 4, and there is no gap in this dimension.

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

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

The description clearly states the action (Read) and the resource (authenticated AdsAgent account profile), and adds a purpose ('for account selection'). It is specific and distinguishes itself from sibling tools like accounts_get_account_detail or accounts_find_owner, which target different account contexts.

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 'for account selection' gives a clear context for when to use this tool. However, it does not explicitly mention alternatives or when not to use it, though the single-purpose nature makes it fairly obvious. Since the sibling list includes many account-related tools, a bit more guidance could help, but the purpose 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?

The readOnlyHint and destructiveHint annotations already establish that this is a non-destructive read operation, and the description does not contradict them. However, the description adds no information about authentication, rate limits, or other behavioral constraints.

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

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

The description is a single focused sentence with no redundant words, and the key action and target 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?

While the output schema is available so return values need not be described, the description omits parameter semantics and usage context. An agent would likely need additional information to correctly call this tool and interpret 'token provenance'.

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

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

The description does not explain either parameter, despite the schema providing no descriptions and the 'operation' parameter having an unclear default of 'pull'. The phrase 'account owner' gives some meaning to ad_account_id, but not enough to fully compensate for the missing schema coverage.

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

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

The description uses the specific verb 'Find' and names the resources 'account owner' and 'token provenance', which distinguishes it from generic account listing tools. It could be more explicit about the input account, but the intent 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?

There is no guidance on when to choose this tool over sibling tools such as accounts_get_account_detail or assets_lookup_business_links. No alternative tools or conditions are mentioned.

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 this as read-only and non-destructive; the description adds operational nuance: data is live from Meta but app bindings are cached, and BM links are excluded. This helps set expectations about staleness and scope without contradicting annotations.

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

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

Three concise clauses with no filler; 'Read live Meta account details' is front-loaded and every added phrase ('app bindings are cached', 'no BM links', sibling pointer) contributes 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?

For a single-parameter read-only tool with an output schema and safety annotations, the description covers the central purpose, caching caveat, and the key sibling for BM topology. Slightly more explicit guidance on when to choose this over account_get_profile would make it 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?

The schema description coverage is 0% and the description provides no guidance on the ad_account_id value's origin or format. The one parameter's name is self-explanatory, but the description does not compensate for the schema 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 action and resource: 'Read live Meta account details.' The caveat 'app bindings are cached, no BM links' and pointer to assets_lookup_business_links clarify scope against BM-topology tools, though it does not explicitly distinguish from the sibling account_get_profile.

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?

Supplies context that this tool exposes account details and explicitly routes 'BM topology' to assets_lookup_business_links, which acts as a when-not alternative. It does not spell out other competing cases such as account_get_profile or list tools.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds 'snapshot read' but this mostly reinforces the read-only nature without introducing new behavioral details like permissions or 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 a single, concise sentence that conveys the essential information without unnecessary words. It is well-structured and easy to parse.

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

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

For a simple read-only tool with one parameter, the description covers the core functionality. It does not detail the return format, but that is not required given the simplicity and the presence of an output schema. Slightly more context about the eligibility criteria could be added, but it is sufficient.

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 only parameter, ad_account_id, is self-explanatory but lacks a formal schema description. The description's mention of 'one ad account' provides minimal clarity. Since schema coverage is 0%, the description partially compensates but does not fully explain the parameter's format or purpose.

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

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

The description clearly states the action (List), the resource (pages eligible for ad creation), and the scope (on one ad account). It distinguishes this from sibling tools like 'assets_list_pages' by specifying the eligibility criterion and account context.

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 mentions 'snapshot read' but does not explicitly state when to use this tool over alternatives such as 'assets_list_pages'. The context is implied but not directly compared to other listing 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?

The description is consistent with the readOnlyHint=true and destructiveHint=false annotations, so there is no contradiction. Beyond that, it discloses no additional behavioral traits—no mention of pagination (despite limit/cursor parameters), scoping, or required authorization. With annotations carrying the safety profile, the description adds no transparency 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?

The description is extremely short with no filler, and the key words are front-loaded. However, it is under-specified to the point that it reads like a label rather than a definition of the tool's behavior, so it does not earn high marks for appropriate sizing.

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 tool with 4 parameters, 0% schema description coverage, and sibling tools with overlapping purposes, a three-word description is not complete enough. It leaves the meaning of required parameters and the exact list semantics unspecified, even though an output schema exists.

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

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

Schema description coverage is 0%, and the description says nothing about the four parameters. It does not explain that ad_account_id and page_id are required, what they scope to, or how limit/cursor control pagination. The description fails to compensate for the absent schema descriptions.

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

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

The description uses a clear verb ('List') and identifies the resource ('IG IDs'), which conveys the core operation. It differentiates from sibling list tools by naming Instagram account IDs specifically rather than pages, ad accounts, or businesses. However, it is terse and does not explicitly situate it relative to siblings like accounts_list_linked_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 guidance on when to use this tool versus alternatives such as accounts_list_linked_accounts or accounts_list_eligible_pages. It does not state whether this is the correct tool for listing Instagram accounts in a page context or an ad account context, and no exclusions are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a hint about pagination ('then paginate') and a routing/BM-links context, but it is too fragmented to provide meaningful behavioral detail beyond the annotations.

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

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

The description is short but not concise in a useful way; it is a fragmented, ungrammatical string that reads like notes rather than a structured definition. It is not front-loaded with the core purpose and contains cryptic references that waste the agent's attention.

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 list tool with 5 optional parameters, no schema descriptions, and an output schema, the description should clarify what is being listed, how pagination works, and what the search/refresh/label parameters do. It does none of this. The output schema exists but the description still fails to provide the minimal context needed to call the tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden for explaining the 5 parameters. It fails to explain limit, cursor, search, refresh, or fb_user_label. The only hint is 'then paginate', which vaguely relates to cursor/limit but adds no concrete semantics.

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

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

The description is a garbled fragment: 'List account routing; then paginate. BM links: assets_lookup_business_links; accounts_find_owner is operator-only'. It does not state a clear verb+resource. The title 'Accounts List Linked Accounts' suggests listing linked accounts, but the description text is incoherent and fails to distinguish this tool from siblings like assets_lookup_business_links or accounts_get_account_detail.

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 mentions 'BM links: assets_lookup_business_links' and 'accounts_find_owner is operator-only', which hints at alternatives, but the guidance is cryptic and lacks a clear when-to-use statement. It does not explain when to choose this tool over accounts_list_eligible_pages or assets_lookup_business_links.

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 indicate destructiveHint=true, so the description does not need to restate destructive potential. It adds some context with 'approved' and 'in-place' but does not describe side effects or irreversibility beyond what annotations imply.

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

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

The description is a single, concise sentence with no redundant words or unnecessary detail.

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

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

For a simple one-parameter confirm action, the description is mostly sufficient, but it omits any explanation of how to obtain confirm_token and what happens after confirmation; annotations cover the destructive nature.

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 input schema provides no description for confirm_token, and the description does not explain what the token is, where it comes from, or how it should be used beyond the obvious inference from the parameter name and confirm action.

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?

Description uses specific verb 'Confirm' and object 'approved in-place creative swap', clearly indicating the action and distinguishing it from sibling deny/prepare operations.

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 guidance on when to use this tool versus alternatives such as ads_replace_creative_deny or ads_replace_creative_prepare; it does not mention that it should follow a prepare step or an approval.

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 annotation already indicates destructiveHint=true, and the description's 'Deny' is consistent with that. The description adds no further context about side effects, reversibility, or consequences of denying, so it does not go beyond the annotations.

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

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

The description is a single, concise sentence with no redundant or vague wording. It gets straight to the point and is easy to understand.

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?

While the tool is simple, the description lacks critical context such as what confirm_token refers to and what the expected outcome of denying is. The presence of an output schema is noted, but the description does not mention any side effects or prerequisites, leaving the tool's full behavior unclear.

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 only parameter, confirm_token, is not explained in the description. The schema provides no description either, leaving the parameter's purpose and format completely ambiguous. The description does not compensate for this lack of semantic detail.

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

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

The description clearly states the action ('Deny') and the object ('a prepared in-place creative swap'), distinguishing it from the confirm and prepare steps among sibling tools. It is specific and unambiguous.

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

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

The description does not explicitly state when to use this tool versus the confirm or prepare alternatives. However, the name and context imply it is the deny step after preparation, but this is not explicitly articulated.

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 that this is a preparation step for an in-place swap, but it does not disclose whether the operation creates a pending state, whether confirmation is required afterward, or what side effects occur. Annotations only say it is not read-only and not destructive, leaving significant behavioral ambiguity.

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 one concise sentence, front-loaded with the verb and object, and contains no filler or redundant wording.

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 operation with eight parameters, a two-phase prepare/confirm/deny structure, and no schema descriptions, the description is too thin. It does not explain parameter roles, required versus optional inputs, or the follow-up confirmation step, so an agent lacks enough context to use the tool reliably.

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?

None of the eight parameters are described, and the schema has 0% description coverage. The ambiguous pairs creative_name/creative_names and new_creative_name/replacement_creative_name are not clarified at all, making correct invocation difficult.

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 ('Prepare'), resource ('existing ad'), and object ('in-place library-creative swap'), which distinguishes it at a high level from confirm/deny sibling tools. However, 'library-creative swap' is somewhat jargon-heavy and not fully explained.

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 guidance is given for when to call this tool versus ads_replace_creative_confirm, ads_replace_creative_deny, or ads_replace_page_prepare. The word 'Prepare' implies it is the first step, but the description does not state the intended workflow or prerequisites.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds that the swap is 'approved' and 'in-place' but does not disclose side effects such as whether the old page is permanently replaced.

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

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

The description is a single concise sentence, front-loaded with the verb and object, and contains no filler or redundant wording.

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 undocumented parameter and no indication of expected outcome, prerequisites, or response behavior, the description is too sparse for an agent to use confidently without external 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?

The only parameter, confirm_token, has no description in the schema and no mention in the tool description. The description does not explain what the token is, where it comes from, or how it is used.

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

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

The description clearly states a specific action ('Confirm') and resource ('approved in-place page swap'), and the phrase 'approved' distinguishes it from deny/prepare variants.

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

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

It gives minimal context—'approved' implies a prior approval step—but does not explain when to use this tool versus the sibling deny/prepare tools or what prerequisites must be met.

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 destructiveHint annotation already signals a destructive operation, and the word 'Deny' conveys the core behavior, but the description does not disclose potential consequences or irreversibility beyond 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?

The description is a single, tight phrase with no unnecessary words or 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?

For a simple denial operation the description is minimal, but it omits useful context such as where confirm_token comes from and what happens after denial, leaving an agent to infer the workflow.

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

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

The only parameter, confirm_token, has no schema description and the tool description does not clarify its origin, format, or purpose. Since schema coverage is 0%, the description should compensate but 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?

The description clearly states the action ('Deny') and the specific object ('a prepared in-place page swap'), making it easy to distinguish from confirm/prepare sibling 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?

It implies a prior 'prepare' step but does not explicitly explain when to use deny versus confirm, nor mention any preconditions or follow-up behavior.

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, and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: it discloses the side effect 'may upload media to Meta' and clarifies that this call only prepares and that a separate confirm applies the change. Return details are omitted but an output schema exists.

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

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

Two compact clauses, front-loaded with the action and followed by the side effect and the required next step. Nothing is padded, though the terseness borders on under-specification for an 8-parameter 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?

For a tool with 8 parameters and 0% schema coverage, the description is too thin: it never explains which parameters drive the page swap or what 'prepare' produces. An output schema does exist, so return values need not be covered, but the parameter and behavioral gaps leave an agent under-equipped.

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 carries the full burden of explaining them and instead adds almost nothing. Only the loose phrase 'page swap' hints at the page-related inputs; ad_id, ad_name, page_ids, facebook_page_id, etc. remain 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?

The phrase 'Prepare page swap' gives a verb and a resource, but 'page swap' is vague and never says it operates on an ad, which is the actual scope implied by the name and required params (ad_id, ad_account_id). It weakly gestures at a sibling with 'Confirm separately,' but does not name ads_replace_page_confirm or otherwise differentiate cleanly.

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

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

It implies the two-step flow by telling the agent the change is not applied until a separate confirm, which is meaningful usage context. However it states no explicit when-to-use vs alternatives, prerequisites, or conditions, leaving most routing inference to the reader.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the mutation risk is covered. The description adds useful context that the tool confirms edits and reads back the resulting copy, but it does not disclose whether the confirm action is irreversible or what side effects occur beyond committing the edits.

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 clauses with no wasted words. It front-loads the main action and adds the read-back behavior in the second clause, making it easy to parse and remember.

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

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

With a single parameter, an output schema, and supporting annotations, the tool is fairly simple; the workflow is also inferable from sibling names like ads_update_copy_prepare and ads_update_copy_deny. However, the complete absence of confirm_token semantics means an agent cannot fully determine how to call the tool without external 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?

The only parameter, confirm_token, is a bare string with no schema description and 0% schema coverage. The description never explains what confirm_token represents, where it comes from, or how the agent should obtain it, leaving a critical gap for correct invocation.

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

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

The description uses a specific verb ('Confirm') with a clear resource ('approved copy edits') and adds a concrete behavioral outcome ('read back copy on the same Ad ID'). It also differentiates from sibling tools like ads_update_copy_deny and ads_replace_creative_confirm by scoping to copy edits on the same ad.

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

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

The phrase 'approved copy edits' clearly indicates this tool should be used once copy edits have been approved, which is useful context. It does not explicitly state when not to use it or name alternatives like ads_update_copy_deny, but the intended workflow placement is reasonably 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. The description adds valuable nuance by clarifying that the destruction is scoped to the prepared edits, not the ad itself. It does not contradict annotations and provides a behavioral detail beyond the raw 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?

The description is a single, front-loaded sentence with no wasted words. It states the action and key outcome efficiently, achieving maximum conciseness while preserving 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?

The description is too sparse for a destructive operation with a required token. It omits the prerequisite that prepared copy edits must exist (via prepare), the meaning of confirm_token, and any irreversible consequences. An agent has no context to call this correctly beyond the name.

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

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

The schema has one required parameter, confirm_token, and the description does not mention it at all. With 0% schema description coverage, the description entirely fails to explain the purpose or origin of the token, leaving the agent without guidance on how to obtain or use 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?

The description clearly states the action: discard prepared copy edits, and the effect: without changing the ad. It distinguishes this from the confirm (apply) and prepare (create) steps, making the purpose unambiguous.

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

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

The description implies the tool is for when you decide not to apply prepared copy edits, but it does not explicitly state when to use it vs. alternatives like confirm, nor any prerequisites (e.g., must have called prepare first). The guidance is only implied.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds only 'preserving media and Page,' a useful guarantee, but it fails to explain what 'prepare' actually does—whether changes are staged before confirmation, whether it mutates anything immediately, or what side effects occur. This is a significant gap for a mutating tool with minimal annotation depth.

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

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

The description is a single, front-loaded sentence that states the core purpose and a key constraint without any redundant wording. Every word earns its place, and it is easily scannable.

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 5-parameter tool operating in a multi-step prepare/confirm/deny workflow, this description is too thin. It does not clarify which fields are required beyond the schema, what the tool returns (even with an output schema, parameter guidance is missing), or any prerequisites like ad existence or permissions. The description leaves critical decisions to inference.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions body/title/description edits, mapping loosely to the body, title, and description parameters, but never explains their format, optionality, or relationships. ad_id and ad_account_id are left entirely to the schema, and no additional semantics are provided for any parameter.

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

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

The description clearly states a specific verb (Prepare), resource (body/title/description edits), and a precise scope (on the same Ad ID, preserving media and Page). This distinguishes it from sibling tools like ads_replace_creative_prepare and ads_replace_page_prepare, which target different components.

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 'preserving media and Page' implies this tool is for copy-only edits, but it does not explicitly say when to use it versus alternatives such as ads_replace_creative_prepare or ads_replace_page_prepare. No mention of the confirm/deny workflow or any disqualifying conditions, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the agent knows this is a safe read. The description adds that accounts are 'cached' (implying possible staleness) and the processing order, which are valuable beyond annotations. It does not contradict annotations.

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

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

Two sentences with no wasted words. The primary action ('List cached accounts') is front-loaded, followed immediately by usage order and a pointer to a related sibling. Efficient and 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 list tool with five optional parameters and zero schema descriptions, the description is insufficient. It does not clarify parameter meanings, the effect of refresh, or what 'cached' implies for data freshness. While an output schema exists, the agent needs parameter semantics to invoke correctly. The reference to BM links is helpful but does not fill the 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%, so the description must compensate. It hints at filtering ('filter') and pagination ('paginate'), which likely map to search, limit, and cursor, but it does not explain refresh or fb_user_label at all. The description gives only a vague operation order, leaving four of five parameters unexplained. This is inadequate given the absence of schema descriptions.

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

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

The description states a specific verb ('List'), a clear resource ('cached accounts'), and a distinguishing characteristic (filtering/pagination). It is distinct from sibling tools like assets_list_businesses and assets_list_pages, and the title reinforces 'Ad Accounts'. The 'BM links' reference further differentiates it from accounts_lookup_business_links.

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

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

It gives clear operational guidance: filter then paginate, indicating the order of operations. It also references assets_lookup_business_links for BM links, implying when that sibling should be used instead. However, it does not explicitly say when to use this tool versus other account-related tools like accounts_get_account_detail or accounts_find_owner, but the scope is obvious enough.

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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that data is cached and that pagination follows filtering, which is useful context beyond the annotations, but it does not explain staleness, refresh semantics, or the nature of the cached 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?

The description is exceptionally concise and front-loaded, with no filler. Every phrase earns its place: 'cached' conveys freshness, 'filter then paginate' gives the interaction order, and the nested-links pointer provides a useful cross-reference.

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?

Despite having an output schema and helpful read-only annotations, the description is too thin for a tool with five undocumented parameters. An agent cannot confidently determine how to use refresh, fb_user_label, or search, or what 'cached BMs' means operationally before calling the 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 must compensate, but it only vaguely mentions 'filter then paginate.' It does not explain limit/cursor mechanics, search semantics, the refresh flag, or fb_user_label, leaving most of the five 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?

The description names a specific verb ('List') and resource ('cached BMs' for Business Managers), which clearly communicates the core purpose. It also hints at a related capability via 'Nested links: assets_lookup_business_links', though it does not fully differentiate this tool from 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?

The phrase 'filter then paginate' implies a browse-and-filter use case, and the nested-links pointer suggests when deeper link data is needed. However, it does not explicitly state when to prefer this tool over siblings like assets_lookup_business_links or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by specifying that results are 'cached', implying data may be stale rather than live, which is a meaningful behavioral trait beyond the annotations.

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

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

The description is a single concise sentence that front-loads the primary action ('List') and includes the key resource and source. Every word earns its place, though it is slightly terse.

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 tool with four parameters, an output schema, and no parameter descriptions in either the schema or the description, the definition is incomplete. It does not explain pagination, filtering, or the role of ad_account_id, leaving an agent to guess how 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% and the description does not explain any of the four parameters (limit, cursor, search, ad_account_id). The description must compensate for the missing schema documentation but fails to do so, leaving parameter meaning entirely to inference from names.

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

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

The description states a specific verb ('List') and resource ('cached Instagram IDs and names') sourced from 'Auto Pull Assets', making the tool's function clear. However, it does not explicitly differentiate from the similar sibling accounts_list_instagram_accounts, leaving some ambiguity about which listing tool to choose.

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 is provided on when to use this tool versus alternatives such as accounts_list_instagram_accounts or assets_list_pages. The mention of 'Auto Pull Assets' implies a specific data source, but no exclusions or selection criteria are given.

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 and non-destructive behavior, so the description only needs to add concrete context beyond that. The 'cached' qualifier is useful behavior and suggests data may be stale, but the description does not explain what `refresh` does, whether it forces fresh data, or how pagination relation to cache behavior.

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

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

The description is compact and front-loaded, using two sentences without unnecessary filler. The phrase 'BM links: assets_lookup_business_links' is cryptic but contributes as a pointer to a related tool, so it 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?

Given the low parameter coverage and five mostly unexplained properties, the description is not sufficient for reliable invocation beyond simple default calls. The output schema exists, but the missing parameter semantics and unclear refresh/filter behavior leave important gaps in contextual completeness.

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 five undocumented parameters, but it adds only generic phrases like 'filter then paginate'. It never explains that `search` filters, `cursor`/`limit` control pagination, what `fb_user_label` does, nor what `refresh` means semantically.

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

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

The description identifies a specific verb and resource: it lists cached Pages with delivery health, which distinguishes it from related asset-listing tools like assets_list_ad_accounts and assets_list_businesses. However, it does not explicitly contrast it with sibling page-related tools such as accounts_list_eligible_pages, so it falls short of full 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 gives a rough operating hint ('filter then paginate') and points to a related tool via 'BM links: assets_lookup_business_links', but it does not explain when to choose this tool over alternatives or when not to use it. No usage exclusions or alternate selection criteria are provided.

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

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

Beyond the readOnlyHint=true annotation, the description discloses that the data is cached, that snapshot edges may be incomplete, and that a missing match does not prove absence of a relationship or ownership. It also notes 'OAuth-safe,' adding auth context not present in the annotations. These are meaningful behavioral disclosures.

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 compact and front-loaded: the core purpose appears first, followed by usage constraints, a caveat, and an auth note. Every sentence adds distinct value, with no filler or redundancy.

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

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

For a read-only lookup with an output schema and no required parameters, the description covers the essential invocation semantics: which identifier to supply, the exclusivity rule, the cached/incomplete nature of the data, and the interpretation of missing results. No critical operational detail is missing.

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

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

Schema coverage is 0%, so the description carries the parameter-semantics burden. It explains that exactly one of business_id, ad_account_id, page_id, or fb_user_label must be chosen and that asset IDs must not be combined with FB-user identities. The parameter names are self-explanatory, and this exclusivity constraint compensates for the empty schema descriptions.

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

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

The description states a specific action and resource: 'Read cached BM links,' which clearly identifies this as a read-only lookup of Business Manager relationship data. It does not explicitly name a sibling tool to differentiate from, so it falls short of a 5, but the resource and verb are specific enough to avoid confusion with the broader assets_list_* tools.

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

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

The description gives clear operational guidance: choose exactly one identifier, and never combine an asset ID with an FB user. It does not explicitly state when to prefer this tool over alternatives or when not to use it, so it misses the top score, but the selection constraint is a strong usage guideline.

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

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

Annotations already disclose that the operation is mutating (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that it refreshes the account and Page cache, but does not explain what this refresh entails (e.g., cache invalidation, data re-fetch, permissions needed, rate limits). It provides some context beyond the annotations but not substantially more.

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

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

The description is a single sentence of seven words, front-loaded with the verb and target. It avoids redundancy and reads well, though it may be overly terse given the ambiguity in the parameter semantics. Still, it earns its place with no fluff.

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 only two parameters and an output schema present, the description still leaves significant gaps: it doesn't clarify what 'connection Page cache' means, whether page_id is always needed, or when to prefer this over assets_refresh_all. An agent would need to infer or look at siblings to use the tool confidently.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It hints that 'account' maps to ad_account_id and 'connection Page' maps to page_id, but it never explicitly names either parameter or explains the role and optionality of page_id. This is minimal value for an agent trying to fill in the required and optional arguments.

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

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

The description clearly states the verb ('refresh') and the specific resource ('one account and its connection Page cache'), distinguishing it from sibling tools like assets_refresh_all by the qualifier 'one account.' Although the phrase 'connection Page cache' is slightly jargon-like, the core action and target are 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 is given on when to use this tool versus the obvious alternative assets_refresh_all, nor any context about prerequisites, whether page_id is required for certain scenarios, or when a single-account refresh is appropriate. The agent is left to infer usage from the name and 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?

The description adds the queuing behavior, implying an asynchronous operation, which is not in the annotations. It does not disclose side effects, scope, or that it likely affects all assets (despite the tool name). Since annotations already mark it as non-read-only and non-destructive, the description's added value is limited to the queue hint.

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

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

One sentence with no filler. It is appropriately small for a parameterless action, and the main verb is 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?

For a parameterless tool with an output schema, the description is minimal but leaves open what 'asset snapshot' means and what the refresh will update. It also doesn't mention how to check the queued job's status, though task-tracking siblings exist. It is adequate but not rich.

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 has zero parameters, so there are no parameter semantics to document. The description doesn't need to elaborate; the empty schema is self-sufficient and the baseline for 0 parameters is 4.

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

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

The description states a specific action ('Queue') on a specific resource ('asset snapshot refresh'), which is more than a tautology. However, it doesn't clarify the scope ('all' assets) or explain what an asset snapshot is, and it doesn't distinguish itself from other refresh tools like fb_users_refresh_routing. This is clear core purpose but with some ambiguity.

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

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

There is no guidance on when to invoke this tool versus the many asset-related siblings (e.g., assets_list_ad_accounts, assets_lookup_business_links). The description doesn't mention that it's an asynchronous bulk refresh, nor does it indicate prerequisites or follow-up steps. This leaves the agent without context for choosing it.

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

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

The description says 'Update', consistent with annotations readOnlyHint=false and destructiveHint=true, and adds that the update affects routing flags. It does not go beyond the annotations to explain consequences such as revoking access or propagation 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?

One short, direct sentence with no fluff. Slightly terse but efficient; could be improved by mentioning the account id or effect, but not necessary for concision.

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

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

Adequate for a simple update tool when combined with the schema and annotations, but it lacks any statement about return value, required ad_account_id, or side effects. It is not misleading, but a bit sparse.

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

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

The description repeats three boolean parameter names but adds no semantics beyond their names; ad_account_id is omitted, although it is required. With schema coverage at 75%, the baseline of 3 is appropriate.

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

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

Clearly states an update action on account permission routing flags and names the relevant fields, which distinguishes it from the assets_list_* and assets_lookup_* siblings. It does not explicitly say 'ad account', but the ad_account_id parameter makes 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?

Provides no guidance on when to use this tool versus alternatives, prerequisites, or whether it should be preferred over other asset update/refresh tools. The action is implied by 'Update', but no explicit usage context is given.

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

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

Annotations only indicate non-readOnly and non-destructive; the description adds the critical behavioral detail that this is a two-step process (prepare draft, then launch_confirm executes after approval). It does not disclose other side effects like rate limits or permission requirements, but given the annotations cover the safety profile, this is a strong addition.

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 core purpose and key decisions. It is concise but slightly dense; the mention of append_mode and target IDs could be clearer, yet it remains efficient without 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?

Given the tool's complexity (nested objects, many options) and the fact that an output schema exists (covering return values), the description still leaves gaps. It doesn't explain the append_mode enum values, the creative_source modes, or policy parameters. While the workflow is clear, an agent would need to rely on the schema for many details, making it 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 compensate. It mentions key parameters (ad_account_id, template_name, creative_source, append_mode, target IDs) and notes that creative_source is singular, but many other parameters (execution, overrides, interest packs, naming, policies) are not explained. The description adds some meaning but is not comprehensive for the large parameter set.

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

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

The description clearly states the tool prepares new ads or appends to an existing campaign/ad set using a saved template and creative source. It distinguishes itself from copy_ad_quick_copy for live-ad copies, giving a specific verb, resource, and scope. This makes the purpose unambiguous and differentiates it from 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?

Explicitly names the alternative copy_ad_quick_copy for live-ad copies, and describes the workflow (prepare, review, then launch_confirm). It also instructs to choose append_mode and target IDs explicitly, guiding when to use append vs new. This provides clear usage context and exclusions.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, which cover safety expectations. The description adds minimal behavioral context ('before prepare') but does not elaborate on side effects or data modifications, so the added value is modest.

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

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

The description is a single, succinct sentence with no redundant words or structural complexity. It is well-formatted and easy to parse, though its brevity contributes to the lack of detail.

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

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

Given the complexity of the input schema (nested objects, required fields, max/min constraints) and the existence of an output schema (not shown), the description is extremely sparse. It fails to explain the request structure, the meaning of 'reconcile', expected outcomes, or any error scenarios, making the tool nearly unusable without external knowledge.

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

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

The schema has a nested request object with multiple required fields (e.g., ad_account_id, target_campaign_id, requested_items), but the description mentions none of them. There is zero parameter explanation, making it impossible to infer correct usage from the description 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 states a specific action ('Reconcile') on a resource ('fixed existing-Ad campaign plans') and a phase ('before prepare'), but it lacks clarity on what 'reconcile' entails and does not distinguish this tool from other campaign-related siblings like campaigns_quick_create or campaigns_recreate_from_task.

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

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

There is no guidance on when to use this tool versus alternatives. The phrase 'before prepare' hints at a workflow sequence but does not clarify selection criteria or prerequisites, leaving the agent without explicit usage instructions.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the description is not contradicting them. But the description adds no behavioral context beyond those flags—it doesn't disclose side effects, what happens to the referenced task, or whether this is a non-mutating preparatory step. Since annotations are present, the bar is lower, but the description still fails to enrich understanding.

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

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

The description is a single sentence, but it is under-specified rather than concise. It lacks front-loaded critical information and contains no structured detail. Every word is generic and could apply to many tools, so it fails to earn its place.

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

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

The tool has an output schema (indicated but not shown), yet the description provides no hint of what the output contains. It also doesn't clarify the workflow—whether this is a step before a confirm/deny pair (as seen in siblings like ads_replace_creative_prepare) or a standalone operation. Given the complexity of the domain and the existence of many related tools, this is severely incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for the parameters. It does not explain what task_ref refers to (a task ID from a create operation?) or what failed_items_only controls (whether to only recreate failed items). The description mentions 'prior create task' but gives no semantic link to the parameters, leaving the agent to guess.

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

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

The description states a specific action ('prepare recreate') and resource ('from a prior create task'), which is not a tautology. However, it is vague about what 'prepare' actually accomplishes—whether it generates a draft, validates the task, or queues a recreation. It doesn't clearly differentiate from sibling tools like tasks_get_create_detail or campaigns_quick_create.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. The single sentence gives no indication of when this is the right tool among the many similar prepare/confirm/deny patterns.

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 read-only and non-destructive behavior. The description adds useful non-obvious behavior: the handle may be expired/not found, the result should be reused while valid, and polling should not be initiated. It doesn’t cover every edge like rate limits, but the annotation coverage is already strong.

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

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

Three sentences with no filler: purpose, accepted input, probable outcome, usage caution, and alternative. The most important discriminators appear first, and every clause adds value.

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

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

For a simple one-parameter read-only checker, this description is complete: it covers purpose, parameter format, return intent, list behavior, and the alternative tool. Output schema is already available, so the return type is documented elsewhere; nothing an agent needs to call the tool correctly is missing.

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

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

With schema description coverage at 0%, the description fully compensates by explaining the accepted handle formats: ci_*, Meta connect_id, or Meta connect_id or fbconn_live_*. This gives the agent concrete selection criteria and is especially important for this one required parameter.

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

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

The description states a specific action ('check'), resource ('existing authorization handle'), and expected outcomes ('status/channel or not_found_or_expired'). It also differentiates this tool from the setup path by naming setup_check_channel_connect, so an agent can pick it correctly without opening sibling schemas.

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

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

It gives clear timing guidance ('after the user finishes'), tells the agent to reuse the link while valid, and forbids automatic polling. It explicitly directs setup connect_id cases to a sibling tool, making the choice between this and setup_check_channel_connect 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 provide readOnlyHint=false and destructiveHint=false, so the description isn't redundant. It adds useful behavioral context: the link is single-use, requires human authorization, and returns a connect_url. This goes beyond the annotations without contradicting them.

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 concise sentences, no fluff. The primary purpose and return value are front-loaded, and the alternative routing is placed second. Every word adds value.

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

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

For a simple create-intent tool, the description covers required information: allowed channels, default mode, return value, and an explicit alternative. It doesn't explain error conditions or prerequisites, but with an output schema existing and the operation being a straightforward link generation, it's sufficiently 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 compensate. It does specify allowed values for channel (meta|google_ads|tiktok) and notes mode=add_connection, giving meaning to both params. However, it doesn't explain other possible modes or elaborate on the mode parameter beyond its default, leaving some semantic gaps.

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

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

The description clearly states the action: 'Create a single-use browser authorization link' and specifies the exact channels (meta, google_ads, tiktok) and mode (add_connection). It also names the return value (connect_url). This distinguishes it from sibling tools like setup_begin_channel_connect by explicitly naming the alternative.

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 explicit guidance: 'Prefer setup_begin_channel_connect when you need its explicit connect_id/check workflow.' This tells the agent when to use a different tool and implies when this one is appropriate (when a simple single-use link is needed). The context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the detail that results are 'redacted', which is useful behavioral context. However, it doesn't mention pagination, rate limits, or any side effects beyond the annotation coverage.

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

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

The description is a single, front-loaded sentence with no filler. It is appropriately concise for a simple list operation, though it could arguably be slightly more detailed without sacrificing conciseness.

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

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

While an output schema exists (so return values are covered elsewhere), the description lacks essential context: no parameter semantics, no usage guidance, and no explanation of what 'redacted' entails. For a tool with three parameters and a large sibling set, this is incomplete.

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

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

Schema coverage is 0% and the description makes no mention of any parameters (limit, cursor, channel). There is no explanation of what each parameter controls, how cursor pagination works, or valid channel values. The description fails to compensate for the undocumented schema.

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

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

The description uses a specific verb ('List') and resource ('platform connections'), which clearly distinguishes it from sibling tools like connections_check_intent and connections_create_intent. However, it doesn't specify what 'platform connections' refers to (e.g., linked ad accounts, pages), leaving some ambiguity about the exact scope.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites, conditions for selection, or contrast with similar listing tools like accounts_list_linked_accounts or assets_list_pages. An agent has no basis to decide this is the right list operation.

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

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

Beyond the sparse annotations, it discloses important behavior and consequences: 'paused is default; inherit may resume spend' warns of potential spend, and 'Prepare ... then launch_confirm after approval' signals this is a staging action, not a live launch. No contradiction with readOnlyHint/destructiveHint.

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

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

Five short sentences front-load the core purpose and constraints, then finish with workflow guidance. No filler or 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?

For a preparation/clone tool, the description includes the essential constraints, default behavior, sibling alternative, and follow-up approval step. The output schema covers return details, so the remaining omissions (start_time, engagement_mode variants) are minor for selection and 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?

With 0% schema description coverage, the description compensates for the key parameters: ad_account_id, exactly one source id, copies range 1-10, and status_option effect. It partially covers engagement_mode via 'keeping each ad's creative' but does not describe start_time or the new_creatives option.

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

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

The description opens with a specific action and resource: 'Prepare a same-account 1:1 campaign/ad-set tree clone, keeping each ad's creative.' It clearly distinguishes the tool from copy_ad_quick_copy by framing this as a tree clone while the sibling is for expanding selected ads.

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

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

The description gives explicit invocation constraints ('Pass ad_account_id and exactly one source_campaign_id or source_adset_id; copies=1-10') and workflow routing ('Use copy_ad_quick_copy to expand selected ads. Review exclusions, then launch_confirm after approval'). It tells the agent when to use the sibling and what to do next.

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

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

Annotations only carry readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description must supply behavioral context. It does: it says this prepares copies rather than executing them, describes the grouped/single behaviors, and notes that partnership preserves the post. It could be more explicit about what the prepared result looks like, but it adds meaningful behavior beyond annotations.

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

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

The description is dense and front-loaded, with each sentence serving a purpose. It sacrifices a little clarity by using shorthand like 'v3' and 'partnership preserves the post', but it remains compact for a tool with a very large nested 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?

Given the tool's complexity, the description covers modes, contract-version constraint, engagement choice, an alternative tool, and the confirm workflow. With an output schema present, it does not need to describe return values; the remaining gaps are minor context around version semantics and the exact meaning of 'prepare'.

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

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

With 100% schema description coverage, the baseline is 3, but the description goes further by mapping request_mode=single to ad_id/source_ad_account_id/target_ad_account_id and grouped to grouped_plan.campaigns, plus explaining engagement_mode choices and v3 status requirements. This is valuable, though not every parameter is elaborated.

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

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

The description opens with a specific verb and resource, 'Prepare copies of live ads', and immediately disambiguates the two request modes. It also names the sibling copy_ad_clone_structure for whole-tree copies, so an agent can distinguish this tool without opening the schema.

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

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

It gives conditional guidance: request_mode=single vs grouped, v3 status requirements, preserve_post vs new_creatives, and explicitly routes whole-tree work to copy_ad_clone_structure. The closing 'Review, then launch_confirm' states the expected workflow.

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

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

Annotations already indicate destructive behavior (destructiveHint=true) and non-read-only (readOnlyHint=false). The description adds 'abandon' and 'reconcile' which reinforces the destructive nature and hints at state cleanup, but does not disclose additional side effects or reversibility beyond the annotations.

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

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

The description is a single concise sentence with no redundant words or elaboration. It is direct and to the point, fitting the tool's simple purpose.

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

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

The tool is relatively simple and the description covers the core purpose. However, given the large set of sibling tools and the lack of parameter explanations, some context is missing—such as when to use this versus creatives_delete or creatives_confirm_upload. No output schema is shown, but the context signals indicate one exists, so return value details are not required.

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 input schema lists 4 parameters (file_hash, idempotency_key, upload_attempt) with no descriptions. The description does not mention any of these parameters or their roles, leaving them completely unexplained. Schema coverage is 0% and the description does not compensate.

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

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

The description clearly states the action: 'Reconcile and explicitly abandon one failed creative upload generation'. The verb 'abandon' is specific and the resource 'creative upload generation' is distinct, differentiating it from sibling tools like creatives_confirm_upload or creatives_request_upload.

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

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

The description implies usage for failed uploads ('failed creative upload generation') but does not explicitly state when to use this tool versus alternatives (e.g., delete, confirm upload). There is no explicit when-not instruction, leaving some ambiguity.

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 indicate this is neither read-only nor destructive, and the description confirms some mutating behavior, but it does not explain what 'confirm' actually does, whether it is idempotent, or what side effects may occur.

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 one concise, direct sentence with no redundant wording. It is well-structured and easy to parse.

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 description lacks important workflow context such as what the response contains, what errors might occur, or what state the upload must be in. While an output schema may exist, the description alone does not give enough surrounding context for reliable use.

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 input schema provides no descriptions, so the description must compensate. It explains that selection_key and file_hash are used to identify and confirm the upload, but it does not clarify the role of folder_name or the expected format/relationship of the parameters.

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

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

The description clearly identifies the action ('Confirm'), the resource ('a prepared creative upload'), and the key identifiers used ('selection key' and 'file hash'). It also naturally distinguishes this tool from related sibling operations like creatives_request_upload and creatives_abandon_upload.

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

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

The description implies this should be used only after an upload has been prepared, but it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or sequencing relative to 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 indicate this is a non-read-only, non-destructive operation. The description adds no further behavioral details such as permissions, side effects, or error conditions, but nothing contradicts the annotations.

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

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

The description is a single, well-structured sentence with no redundant phrasing. It directly conveys the action and scope without extra fluff.

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

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

For a simple creation tool with one parameter, the description is mostly complete, including the workspace scope. It omits potential edge cases like duplicate folder names or naming restrictions, but given the low complexity, this is a minor gap.

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

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

The only parameter folder_name is left entirely to schema inference; the description does not explain its meaning, constraints, or acceptable values. Schema coverage is 0%, so the description should compensate but 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?

The description clearly states the specific action 'Create a creative folder' and scopes it to 'the current workspace', which distinguishes it from sibling tools like creatives_list_folders or creatives_delete. The verb and object are 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 explicit guidance is given about when to use this tool versus alternatives. The description simply states the action without mentioning circumstances, prerequisites, or contrasting with other folder-related ops.

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's 'Delete' aligns with the destructiveHint: true annotation and readOnlyHint: false. However, it does not disclose permanence, cascading effects, or permission requirements, though the destructive annotation covers the core side effect.

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

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

The description is a single, focused sentence with no filler or redundant wording. It directly communicates the primary operation and identifier.

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

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

For a simple delete operation, the description identifies the target and action, and an output schema exists. However, it lacks usage context and alternative guidance, leaving the agent to infer when this destructive action is appropriate.

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

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

The description adds some meaning to the lone 'selection_key' parameter by indicating it can be a selection key or a creative reference, but it does not specify format, requiredness, or possible ambiguity. Schema coverage for the single parameter is present but shallow.

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

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

The description clearly states the action ('Delete'), the resource ('owned creative'), and the identification method ('by selection key or creative reference'). It is concise and distinct from sibling tools that list, get, upload, or confirm creative actions.

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 is provided on when to use this tool versus related creative operations such as abandon_upload, confirm_upload, or list. The description states what it does but not the context or conditions that should trigger its 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds no behavioral detail beyond the word 'Get'. It does not mention what is returned, whether the media is loaded remotely, or any side effects or prerequisites.

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 extremely short, but this is under-specification rather than effective conciseness. It front-loads nothing useful and leaves the only parameter and usage semantics entirely unexplained.

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?

While the tool is simple and has an output schema, the description is too sparse to support correct invocation. It fails to clarify what media is retrieved, how selection_key filters results, or how this differs from sibling list tools.

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

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

The schema has 0% description coverage for the only parameter, selection_key, and the description does not mention it at all. The agent is given no hint about what selection_key means, its format, or when it is needed.

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 'Get media' names a verb and a resource, but not with enough specificity to distinguish it from creatives_list or other media-related tools. It does not state whether it fetches a single creative, a set, or by what criteria.

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 is provided on when to use creatives_get versus creatives_list, creatives_list_folders, or other read tools. The description gives no context about intended use or selection logic.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read operation. However, the description adds no behavioral context beyond that, such as how pagination works via the cursor parameter or any batch size limits. It is not contradictory, but it adds no value over the annotations.

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

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

The description is only four words, which is extremely concise, but it is under-specified rather than appropriately sized. It lacks any structural detail or front-loaded context. This is a case of under-specification, not good conciseness.

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

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

For a tool with a required array parameter, an optional pagination cursor, and an output schema, the description is completely inadequate. It does not explain what the output represents, how selection_keys map to media, or when to use this tool. The description provides no meaningful context for the agent to correctly invoke 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%, so the description carries the full burden of explaining parameters. It fails entirely. The required 'selection_keys' array and optional 'cursor' are not explained at all. The description adds no meaning beyond the bare schema, leaving the agent to guess how to populate these parameters.

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

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

The description 'Get media batch' is extremely vague. It does not specify what constitutes a 'batch', what 'media' refers to in this context, or how it differs from sibling tools like creatives_get (likely single retrieval) or creatives_list (likely list all). It fails to distinguish its purpose from those alternatives.

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

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

No guidance is provided on when to use this tool versus creatives_get or creatives_list. The description does not mention selection_keys, pagination via cursor, or any conditions that would make this the appropriate choice. There is no mention of alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral details beyond that: the default scope (whole library), pagination requirement (follow next_cursor), and limit constraint (<=50). It also mentions 'trust scope' which indicates the scope parameter controls filtering. These are not in the annotations, so the description adds meaningful behavioral context. It does not contradict annotations.

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

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

The description is front-loaded with the core purpose, which is good. However, it includes a lengthy tangent about upload instructions and a URL that is unrelated to the tool's primary function. While this serves as a when-not-to-use note, it could be more concise. The latter part is terse but dense. Overall, it has some bloat but is not overly long, earning a middle score.

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

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

The tool has 8 optional parameters with no schema descriptions, and the description only explains a few (scope, limit, cursor). It omits guidance on q, sort, created_from/to, folder_name, leaving agents to guess their purpose. The output schema exists, which may cover return values, but parameter semantics are significantly incomplete. For a listing tool with many filters, this is a notable gap.

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

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

Schema description coverage is 0%, so the description must compensate for the 8 parameters. It only partially addresses a few: 'scope' (via 'trust scope' and default), 'limit' (via 'use limit<=50'), and 'cursor' (via 'follow next_cursor'). Parameters like q, sort, created_from/to, folder_name are not explained at all. The description adds minimal value for most parameters and fails to guide the agent on how to use the filtering options.

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: 'List owned creatives; default is the whole library.' It clearly identifies the tool's function (listing creatives) and distinguishes its scope from other creatives tools like creatives_get (single item) and creatives_list_folders (folders only). The phrase 'default is the whole library' adds important context about the default behavior, making the purpose unambiguous.

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

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

The description provides explicit when-to-use guidance by stating 'List owned creatives' and also when-not-to-use: 'For upload/how-to help, give [Creative library]... No list call is needed just for instructions.' It also gives operational constraints: 'trust scope, use limit<=50 and follow next_cursor with unchanged filters.' This clearly tells the agent when to invoke this tool and how to handle pagination and limits, with no ambiguity.

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 readOnlyHint annotation already indicates the read-only nature of the tool, and the description aligns with that. It does not add extra context such as rate limits or side effects, but given the annotation, the bar is lower.

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

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

The description is a single, concise sentence that directly states the tool's action, with no unnecessary words.

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

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

For a simple list operation, the description is complete. It does not need to explain return values since an output schema is present, and the scope is clear.

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 parameters limit and cursor are defined in the schema but without descriptions. The tool description does not explain their meaning (e.g., limit for page size, cursor for pagination), leaving the agent to infer their semantics.

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

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

The description 'List creative folders' uses a specific verb and resource, clearly distinguishing it from sibling tools like creatives_list (which lists creatives) and creatives_create_folder (which creates folders).

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

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

The description does not explicitly state when to use this tool versus alternatives, though the name and verb imply its purpose. No guidance on pagination or error handling is provided.

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

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

The description does not disclose side effects, such as whether a pending upload session is created, how long metadata remains valid, or whether subsequent confirmation is required. Annotations are sparse (readOnlyHint false, destructiveHint false) and provide little additional transparency.

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

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

The description is a single concise sentence with no fluff, but it is vague ('bounded upload metadata') and does not add structural information. It is not poorly organized, but it omits useful details.

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 seven parameters and no parameter descriptions, the description is not complete enough for correct use. Although an output schema exists, the description does not explain the upload workflow, prerequisites, or how the returned metadata fits with sibling confirm/abandon tools.

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 explains none of the seven parameters. It does not clarify file_hash algorithm, file_size units, content_type format, or the purpose of upload_attempt and idempotency_key.

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

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

The description states a specific action ('Prepare a creative upload') and resource ('creative upload'), and indicates an output ('return bounded upload metadata'). It distinguishes this from sibling tools like creatives_confirm_upload and creatives_abandon_upload, though it does not explicitly name 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?

The description gives no explicit guidance on when to use this tool versus alternatives such as creatives_confirm_upload or creatives_abandon_upload. It implies preparation but does not state the workflow or when not to use it.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, lowering the transparency burden. The description confirms the read-only list operation by repeating 'List' and adding account-account usage expectations. It adds useful context about account identity and page routing, but it does not disclose behavior beyond what the annotations can convey, such as pagination mechanics, cache/refresh mechanics, or access restrictions.

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

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

The first sentence is front-loaded and gives the core semantics, but the remaining sentences mix tool suggestions, permission notes, and an external support link. These are operationally relevant yet not all necessary for invoking fb_users_list correctly, and the description overall is noticeably longer than the primary purpose requires.

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, annotations, and no required parameters, the tool is callable with only basic guidance, and the description supplies pagination intent and access rules. However, five parameters are entirely undocumented at the schema level and largely unexplained in the description, particularly refresh and search, which leaves part of the tool's behavior opaque.

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 unannotated parameters. The phrase 'by owner_ref and label; filter then paginate' loosely maps to fb_user_label and cursor/limit concepts, but the schema has five parameters and the description never mentions search, refresh, limit, or cursor, and owner_ref is not even a schema property. This leaves the agent without meaningful semantic guidance for most parameters.

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

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

The description states a specific verb and resource ('List FB users by owner_ref and label; filter then paginate', and it clearly frames the operation as a read operation. However, it references 'owner_ref as if it were a parameter when the schema only exposes fields like fb_user_label and search, which creates slight ambiguity against sibling tools. Still, it is distinct from sibling update/mutation tools.

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

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

The description gives contextual guidance about which tools to use for business-manager links and when accounts_find_owner applies, and it adds access-safety instructions about ordinary users and internal/admin pages. However, it does not explicitly state when to prefer fb_users_list over alternatives or provide a clean 'use when vs. use instead' rule. Usage guidance is implied rather than formally 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 indicate readOnlyHint=false and destructiveHint=false, but the description adds little beyond stating 'Queue'. It does not disclose whether the operation is synchronous or asynchronous, what the refresh entails (e.g., updating routing tables), or any prerequisites like the user being bound. With no annotation coverage for these details, the description carries the burden but fails to elaborate.

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

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

The description is a single, focused sentence with no extraneous words. It front-loads the primary action and object, making it immediately scannable. Perfectly concise for a simple 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?

Despite having an output schema, the description omits crucial context: what a successful refresh looks like, whether the user must be pre-bound, and what happens to routing after queuing. Given the tool's role among many FB user and asset management siblings, this lack of detail leaves the agent guessing about side effects and prerequisites. The description is too sparse for a complete understanding.

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 clarify the parameter. It says 'for one FB user', which implies fb_user_label identifies the user, but it does not explain what a 'label' is, how to obtain it, or whether it is required (schema shows required: 0). This adds some meaning but leaves ambiguity about the parameter's format and necessity.

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

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

The description states a specific action ('Queue'), a precise object ('ad-account routing refresh'), and scope ('one FB user'), clearly distinguishing it from sibling tools like assets_refresh_all (which refreshes all assets) and fb_users_update_label (which updates labels). The verb+resource+scope pattern makes the purpose unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is the tool for refreshing a single user's routing, nor does it contrast with related tools like assets_refresh_all or fb_users_update_permissions. The agent must infer usage from the name alone.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=false, so the safety profile is covered. The description adds no behavioral context about what 'label' means, whether it overrides an existing label, or what the three parameters (label, owner_ref, fb_user_label) do relative to each other.

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 efficient sentence, front-loaded with the action and target. However, it is too short to cover the required parameter semantics.

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

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

Output schema exists so return values needn't be explained, but the description fails to compensate for 0% parameter coverage or to explain the mutation's prerequisites and effects for a destructive update tool.

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

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

Schema description coverage is 0% and the description does not explain any of the three parameters. The relationship between 'label', 'owner_ref', and 'fb_user_label' is left entirely 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 (Set) and resource (display label for FB user connection), distinguishing it from siblings like fb_users_list or fb_users_update_permissions. It doesn't explicitly disambiguate from fb_users_refresh_routing, but the resource 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?

No when-to-use guidance, no prerequisites, no mention of alternatives such as fb_users_list for discovery or fb_users_update_permissions for other edits.

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 indicate destructiveHint=true and readOnlyHint=false, so the description's 'update' is consistent. However, the description does not add extra context about side effects (e.g., token invalidation, propagation delays, or confirmation requirements). Given the annotations, the bar is lower, but no additional transparency is provided.

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

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

The description is a single, concise sentence with no fluff. It front-loads the verb and directly states the object and attributes, making it easy to parse and act upon.

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

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

For a simple flag-update mutation, the description covers the core action and most parameters. However, the missing explanation of fb_user_label and lack of any note about required fields or expected output leave some gaps, though the tool's basic purpose is clear.

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

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

The schema has no parameter descriptions (0% coverage). The description explains the three boolean flags but omits fb_user_label, which is the target user identifier. This leaves a critical parameter ambiguous and fails to fully compensate for the absent schema descriptions.

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

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

The description clearly states the action ('update') and the target ('one FB user's flags') and enumerates the specific flags (allow_create, allow_pull, allow_decision). It distinguishes itself from sibling tools like fb_users_update_label and fb_users_bind_token by specifying exactly which attributes are modified.

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

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

The description implies when to use the tool (to change user permission flags) but does not explicitly contrast it with alternatives or provide conditions or prerequisites. It is adequate but lacks explicit usage guidance beyond the basic imperative.

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, and openWorldHint=false. The description adds only 'queue,' implying an asynchronous side effect, but says nothing about confirm_export, permissions, export versus queue behavior, rate limits, or what happens to previously queued exports.

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

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

The description is a single short sentence with the action front-loaded and no filler. It is arguably too terse for an 11-parameter tool, but the wording itself is efficient and 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 an 11-parameter export tool with no schema descriptions, the one-sentence description is far from complete on usage, parameter meaning, and side effects. The output schema may cover return values, but the description still leaves critical call-time context missing.

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

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

Schema description coverage is 0% across 11 parameters, so the description must compensate and does not. It never mentions required group_by, date_from/date_to, filters, search, attribution, export_mode, product_ref, product_name, ad_account_id, or confirm_export.

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 ('Export or queue CSV'), so the core action is identifiable. However, 'for one bounded scope' is vague and there is no differentiation from sibling insight/export tools, so an agent cannot easily tell when this tool is the right choice.

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

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

No when-to-use guidance is provided, and no alternatives or exclusions are named. 'Export or queue' hints that two modes exist but does not explain when each applies, what prerequisites are needed, or how this differs from insights_pull_insights or insights_query_*.

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 says 'Read', which aligns with the readOnlyHint annotation. It does not mention side effects or return format, but since the annotation already covers safety, the description is adequate but not enhanced.

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

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

The description is a single concise sentence with no redundant wording. It is efficiently written.

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

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

For a simple read-only tool, the description is sufficient for basic understanding. It could mention that it returns coverage information, but the lack of detail is acceptable given the tool's simplicity.

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 has no parameters, and the schema coverage is 100% (empty). The description does not need to explain parameters, so this is handled implicitly.

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

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

The description clearly states a read operation on 'stored date coverage', but it could be more specific about what 'date coverage' entails. It is understandable but not as precise as desired.

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 is provided on when to use this tool versus the numerous sibling tools. It does not differentiate its use case or mention any context where it is preferred.

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 indicate readOnlyHint=false and destructiveHint=false, and the description adds the notion of a 'fresh pull', implying it refreshes or updates insight data. This adds a small amount of context beyond annotations, but it does not disclose any side effects, rate limits, or what exactly happens to existing rows. The description adds modest value but leaves important behavioral details unspecified.

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

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

The description is a single sentence with no filler, which is concise. However, it is so terse that it omits essential details like parameter meaning and usage context, making it under-specified rather than appropriately concise. It is front-loaded with the core action, but brevity comes at the cost of completeness.

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

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

The tool has a single optional parameter and an output schema, but the description does not explain what 'standard Meta insight rows' means, how the queue behaves, or what the output represents. It does not need to describe return values if an output schema exists, but it still should clarify the parameter and any important behavior. For a tool that initiates a pull, this is insufficient for an agent to call it correctly.

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

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

The schema has a single parameter 'days' with default 30, and schema description coverage is 0%. The description does not mention the parameter at all, so an agent has no indication of what 'days' controls, its valid range, or its effect on the pull. This is a critical gap because the description fails to compensate for the missing schema 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 uses a specific verb 'Queue a fresh pull' and identifies the resource as 'standard Meta insight rows', making the core action clear. It does not explicitly differentiate from sibling tools like insights_query_overview or insights_get_date_range, but the action of queueing a refresh is distinct enough for an agent to infer a difference, though not with high confidence.

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 is provided on when to use this tool versus the many other insights tools (e.g., insights_export_csv, insights_get_date_range, insights_query_overview). The description does not state any conditions, prerequisites, or exclusions, leaving the agent to guess 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?

The description only says 'Pull splits,' which implies a read-like retrieval operation but discloses nothing about scope, filtering, side effects, permissions, or behavior beyond the annotation values. Since readOnlyHint is false, the read-only nature is not even guaranteed by annotations.

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

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

While extremely short, this is under-specification rather than effective conciseness. Two words cannot meaningfully describe a 9-parameter tool and no structured information is 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?

For a tool with 9 parameters, 3 required fields, 0% schema coverage, and no descriptive guidance, the definition is far too incomplete. An agent cannot determine valid combinations, the meaning of 'splits,' or how this relates to the broader insights tool family.

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

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

With 0% schema description coverage and 9 parameters, the description carries the full burden of explaining parameters, but it mentions none of them. The agent gets no help understanding required fields like level, date_from, date_to, or optional filters like ad_ids, breakdowns, product_ids, product_refs, product_names, or conversion_event.

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 'Pull splits' is a vague, near-tautological restatement of the tool name. It does not specify that these are product breakdowns for insights, nor does it distinguish this tool from siblings like insights_read_breakdowns or insights_pull_insights.

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 is given about when to use this tool versus alternatives. There are several closely related insights tools, but the description offers no context, exclusions, or criteria to select this one.

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

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

Annotations already mark this as read-only and non-destructive, so the description's main added behavior is 'Cached batch' and 'Partial=unknown, never zero'. These statements disclose cache staleness and how missing results are represented, which matters for interpreting the output. This adds useful behavior not present in the annotation structure.

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 very short but reads as telegraphic fragments rather than structured sentences. 'Partial=unknown, never zero', 'page for all', and 'Use advertised insights_query_consistent' are cryptic and require user intuition to decode. It packs facts but not in a clear, front-loaded, readable structure.

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

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

Given 13 parameters and no schema-level descriptions for them, the output does provide essential guidance for the scopes array, date format, group_by, and page. But it omits meaning for search, sorting, view_mode, management, attribution, and page_size, and does not establish all field interactions. It is minimally adequate for constructing a basic call, not for confidently using all capabilities.

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

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

The schema description coverage is 0%, so the description has to compensate for the opaque 'scopes' objects. It clarifies that each scope needs product_ref/product_name/ad_account_id and gives date format and page usage, which is valuable. However, 9 or more parameters remain unexplained, such as sort, view_mode, management, search, and attribution; defaults and enums help but the description only partly fills the coverage gap.

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

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

The description says 'Cached batch' but never states what this tool actually does or returns, e.g., that it queries a batch of cached insights. It jumps straight to parameter requirements, leaving the purpose mostly to be inferred from the tool name and the mention of a sibling. This is more than a tautology but still vague.

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

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

The line 'Use advertised insights_query_consistent' gives a pointer to an alternative, implying this tool is for cached data and the sibling is for consistent data. However, it does not explicitly explain when to prefer this tool over other insight siblings or under what conditions to choose the consistent variant. The guidance is present but implicit and incomplete.

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