Pollen — Managed Agent-Readiness Layer

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

Annotations already indicate readOnlyHint=falseaine, so the description's disclosure that it 'Creates their Merchant Center account' adds specific side-effect context beyond the annotation. The precondition phrasing also conveys the stateful nature of the tool. However, it doesn't mention failure modes or what happens if called in an invalid state, which is a minor gap.

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

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

The description is two sentences with no filler. The critical state (tos_required) is front-loaded, the usage condition is explicit, and the side effect is stated. Every clause earns its place.

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

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

For a zero-parameter, no-output-schema tool, the description is fully sufficient: it states the prerequisite, the triggering state, the source of the termsUrl, and the outcome. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters and the schema is fully covered (empty object), so there is nothing for the description to clarify. The baseline of 4 for no-parameter tools is appropriate; no additional param information 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 states a specific verb ('Resume'), a precise resource ('greenfield Google connect paused on Terms-of-Service acceptance'), and the concrete outcome ('Creates their Merchant Center account and finishes the handshake'). It clearly distinguishes itself from sibling tools like connect_google and get_google_connect_status by naming the exact state (tos_required) it acts on.

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 explicitly says 'Only call this after the merchant has confirmed they accept the Google Merchant Center ToS', and references the sibling get_google_connect_status as the source of the termsUrl. This is a clear when-to-use condition that prevents misuse, effectively also stating when not to call 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?

Beyond the destructiveHint annotation, the description explains that it overwrites human-facing content, requires showing the candidate and obtaining explicit approval, and notes that hedged sentences and enrichment meta-commentary are stripped. This gives the agent a concrete understanding of side effects and safeguards, adding real value over the annotation.

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

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

Every sentence earns its place: the core action, the clarification of the candidate source, the approval requirement, and the applicability threshold. It is front-loaded with the action and avoids redundancy, making it efficient 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 destructive write operation with an approval workflow, the description covers the essential prerequisites: the source of the candidate, the sanitization behavior, the approval requirement, and the condition for use. It does not specify the return value, but that is not critical for a one-parameter write operation without an output schema.

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

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

The single parameter productId is fully described in the input schema (100% coverage), so the schema already carries the meaning. The description adds no additional semantics beyond referencing get_product as the source of the candidate, which is implicit from the purpose. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Replace') and resource ('one product's shopper-visible store description') and clarifies it uses the sanitized enriched version (storefrontDescriptionCandidate) rather than the raw agentDescription. It clearly distinguishes from get_product (which provides the candidate) and other enrichment tools, leaving no ambiguity about what the tool does.

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

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

It provides a clear applicability condition ('Only applies when the store's current description is thin (<200 chars)') and a mandatory approval step ('MUST show the merchant that exact candidate first and get their explicit approval'). It does not explicitly name alternative tools, but the condition and approval requirement are sufficient to guide an agent's decision.

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 destructiveHint=false and readOnlyHint=false, which is neutral, but the description provides crucial behavioral detail: it is queued asynchronously on a worker and the agent must poll get_fix_opportunities fixStatuses for progress. It also clearly states a fill-only-empty policy, which is non-destructive in nature but not fully captured by annotations. This goes beyond annotations to disclose the async behavior and non-overwrite guarantee.

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 dense but highly informative 3-sentence block. It front-loads the core purpose and the four fix types immediately, then provides the critical fill-only-empty behavior, and finally the queuing/progress detail. No wasted words; every sentence earns its place, and the structure is logical for decision-making.

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 is a single-parameter, mutation-style tool with no output schema, the description covers what action each fixType takes, the non-destructive fill-only behavior, and the async nature with how to track progress. It is missing explicit prerequisites (e.g., whether enrichment is required for tags or brand, or if the store must be connected), but those are likely contextually inferable from sibling tools. The core call semantics are 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 input schema has one parameter, fixType, with an enum, but schema description coverage is 0%, meaning the schema does not explain the enum values. The description compensates by explicitly listing and explaining each enum value ('seo' fill empty SEO titles + meta descriptions, etc.), which is exactly the semantic meaning an agent needs. This adds significant value beyond the bare enum.

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 'Run' with the resource 'Pollen's automated catalog-wide fixes' and enumerates the four specific fix types (seo, tags, altText, brand) with concrete examples of what each does. It distinguishes itself from sibling tools like apply_description, which is about a single product description, and get_fix_opportunities, which is about listing opportunities rather than applying fixes.

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 this tool: when you need to apply a fix that fills empty values, and it explicitly notes that values already set are never touched, which guides usage. It does not explicitly name alternatives or when-not-to-use, but the sibling list and context make it clear that get_fix_opportunities is for discovery and this is for execution. Excluding explicit alternatives is a minor gap.

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?

Even though annotations provide readOnlyHint=false and destructiveHint=false, the description goes beyond annotations by explaining that the tool starts an interactive flow requiring human intervention, and that it may pause at intermediate steps. It also clarifies that once active, the enriched catalog is published automatically, which is a behavioral consequence not captured 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?

The description is concise and front-loaded, leading with the core action and immediately stating the key behavioral requirement (human must open the URL). Each subsequent sentence adds critical routing information without waste, making it 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?

Given zero parameters, no output schema, and moderate complexity (interactive OAuth flow), the description fully covers what an agent needs to know: the human-in-the-loop requirement, follow-up steps, potential pauses, and automatic post-connection behavior. No critical information 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, and schema coverage is 100% (trivially, since there are no properties). The description does not add parameter-level semantics because none exist, so a baseline score of 3 is appropriate for the context.

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's purpose: starting or restarting the connection of the merchant's Google Merchant Center to Pollen. It distinguishes itself from siblings by mentioning the resulting authUrl and the follow-up flow, making it distinct from other connect tools like connect_meta.

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 explicitly states that the human must open the authUrl in a browser, which is a critical usage constraint. It also directs the agent to call get_google_connect_status after approval and mentions the possibility of pausing on an account picker or ToS acceptance, with clear next steps (pick_google_account or accept_google_terms). This is exemplary usage guidance.

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

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

The annotations only indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=false, but are not fully self-explanatory. The description adds critical behavioral context: the tool returns an authUrl that requires human interaction, it may pause on a picker, and the catalog is automatically published once active. However, it doesn't detail error cases or how the 'restart' affects existing connections, but the added context is substantial 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 a single, focused paragraph that leads with the core action, then adds essential workflow details in a logical order. Every sentence carries weight: it explains the human step, the status check, the potential picker pause, and the automatic publishing. 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?

Given that the tool has no parameters and no output schema, the description covers everything an agent needs to know: prompt for human action, next steps, possible branching, and outcomes. It is complete for the complexity of the tool and complements the annotations.

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 schema provides no parameter information. The description properly states that no parameters are needed and instead explains the return value (authUrl) and the required human step. Since the schema is empty, the description fully compensates for the lack of parameter details, earning a strong score.

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 ('Start or restart connecting'), identifies the resource (Meta Business catalog) and the platform (Pollen), and distinguishes itself from siblings like connect_google and get_meta_connect_status. It also covers the 'restart' aspect, which is not evident from the name alone.

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

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

Provides explicit guidance on when to use this tool (to start or restart the connection) and what to do next (call get_meta_connect_status). It also routes to alternative tools for picker selection (pick_meta_business / pick_meta_catalog), ensuring the agent knows the full workflow and how to handle the flow.

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 discloses that the tool is asynchronous: it returns a job reference and directs the agent to get_pipeline_status for progress. This adds meaningful behavioral context beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false. No contradiction with annotations.

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

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

The description is short and front-loaded: it opens with the action and scope, then gives the async behavior and progress-checking instruction. The closing 'primary do the work action' phrase is somewhat vague but is brief and does not meaningfully clutter the description.

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

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

For a zero-parameter async trigger, the description covers the key operational facts: what is enriched, what the call returns, and how to monitor it. It does not elaborate on downstream side effects or the exact meaning of enrichment, but the sibling tool set and annotations provide enough surrounding 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 input schema has zero parameters, so there is no parameter-level burden on the description. The description still provides useful context about what the parameterless call operates on: the full catalog of PENDING and FAILED products.

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 states a specific verb ('Run enrichment') and a precise resource scope: the merchant's full catalog, filtered to PENDING + FAILED products. This distinguishes it from a single-product tool like enrich_product and adds operational detail beyond the tool name.

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

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

The description labels this as 'the primary do the work action,' which implies broad whole-catalog usage, and the PENDING + FAILED scope gives context. However, it does not explicitly state when to avoid it or name alternatives such as enrich_product for single-product enrichment.

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 meaningful behavioral context beyond annotations by disclosing that the call returns immediately with a job reference and that progress must be polled via get_pipeline_status. It does not describe the eventual effect of enrichment or any limits, but the async behavior is the critical missing piece not present in the annotations.

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

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

Two compact sentences front-load the action and then give the essential async follow-up. There is no filler or redundant restatement of the schema.

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

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

For a one-parameter async trigger with no output schema, the description provides the essential invocation and follow-up context. It is slightly thin on what 'multimodal enrichment' produces or changes, but the agent has enough to call correctly and monitor progress.

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

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

Schema coverage is 100%, so the single productId parameter is already documented as a Pollen internal product ID. The description's 'single product' phrasing mildly reinforces that productId refers to one product, but it adds no format or additional 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 opens with a specific verb-resource pair: 'Run Pollen's multimodal enrichment on a single product.' It also differentiates from its sibling enrich_all_products by emphasizing 'single product' and from get_product/update_product_facts by framing enrichment as a distinct operation.

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

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

It clearly frames this as the single-item enrichment path and tells the caller to check get_pipeline_status after the call. It does not explicitly name enrich_all_products as the batch alternative, so it stops short of the explicit when-not/alternatives guidance needed for a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the specific data points returned (plan, agent-ready %, product counts, timestamps), which is useful context. However, it doesn't describe the return format or any potential latency/rate-limit behavior. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and then lists the specific data points. The usage guidance is appended as a second sentence, making the whole description compact and efficient with no wasted 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 zero-parameter, read-only tool with annotations covering safety, the description is nearly complete. It tells the agent what data will be returned and when to use it. The only minor gap is the lack of detail on the exact response structure, but since there is no output schema and the tool is simple, this is a minor omission.

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 schema is trivially complete. The description adds value by explaining what the summary contains, which is the only meaningful semantic content an agent needs. Baseline 4 is appropriate for a no-parameter tool.

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's function: retrieving a high-level summary of the merchant's Pollen account, listing specific data points (plan, agent-ready %, product counts, timestamps). It distinguishes itself from sibling tools by focusing on account-level status rather than deep audits, pipeline status, or network 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?

The description explicitly tells the agent when to use this tool: 'Use this first if the user asks 'where do I stand?' or 'what's my status?'' This provides clear context and a direct trigger, making it easy for an agent to select this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond that: it discloses the access-gating behavior (requires payment, returns an unlock message without access) and precisely enumerates the report's contents. This gives the agent a clear picture of what will happen when invoked, both with and without entitlements.

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 first sentence front-loads the report contents, and the second covers the access condition and fallback. Every phrase earns its place, and the structure 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?

With no input schema and no output schema, the description must carry the full weight of explaining what the tool returns and any preconditions. It does both: it lists the three report components and explains the gated behavior. For a zero-parameter read-only report tool, this is complete enough for an agent to decide whether to call it and what to expect.

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

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

There are zero parameters and schema description coverage is 100%, so the schema imposes no burden. The description does not need to explain any input semantics; it focuses on the output. Thus the baseline of 4 for a zero-parameter tool applies, and the description meets it without needing parameter elaboration.

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 what the tool returns: a Deep Audit report containing three specific components (AI answer-visibility test, catalog fix plan, worst-scoring products with missing attributes). It is distinct from sibling tools like get_fix_opportunities or get_network_insights by naming the exact report contents, so an agent can select it unambiguously.

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 an access prerequisite (paid plan or $9 purchase) and the fallback behavior when access is missing, which is a usage condition. However, it does not explicitly state when to prefer this tool over alternatives like get_fix_opportunities or get_network_insights, nor does it provide guidance on which scenarios warrant this specific report. The usage context is implied but not differentiated.

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 safety is covered. The description adds meaningful behavioral context by detailing the nature of the output (points, counts, checklist, candidates) without contradicting annotations. This enriches the agent's understanding beyond the bare 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 dense sentence that packs a lot of information, followed by a short trigger guidance. It's front-loaded with the primary purpose before the 'start here' instruction. Slightly long but every clause adds value; 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?

Since there's no output schema, the description must convey what the tool returns. It lists all major output categories (points lost, fixable counts, checklist, candidates) in enough detail for an agent to know what to expect. Format and structure are not specified, but for a read-only analysis tool this is adequate. Could add a note about interactivity (e.g., awaiting approval), but it's covered implicitly.

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 schema coverage is trivially 100%. Per the rubric, 0 params = baseline 4. The description correctly contains no parameter details because none exist.

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

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

The description explicitly states the tool analyzes agent-readiness gaps and enumerates the specific outputs (points lost, fixable counts, 'needs you' checklist, description candidates). It also provides a distinct usage trigger ('what's wrong?', 'how do I improve my score?'), which clearly separates it from siblings like get_deep_audit or get_pipeline_status.

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

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

Gives explicit when-to-use guidance with two example user queries. It doesn't mention when not to use it or name alternatives, but the trigger phrase makes the intended scenario unambiguous. Could be improved by noting it's a starting point vs. more granular tools, but not essential.

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 it read-only and non-destructive. The description goes well beyond by enumerating the full status state space, explaining transient vs terminal states, describing connector_pending as a server-side setup step, and noting that active status includes funnel stage and approval counts.

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 and then delivers a compact, separated status list. Every parenthetical adds operational value, such as next actions or clarification, with no filler.

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

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

For a zero-parameter read-only tool with no output schema, this description is highly complete: it covers all status values, what they mean, what to do in actionable states, and what extra data appears when active. The lack of a formal JSON shape is acceptable because the semantics are fully conveyed.

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 is no parameter burden to explain. The schema already covers this with an empty object and full coverage. The description instead enriches the output semantics, which is the appropriate use of its space.

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 resource (Google connection) and the action (reporting its status). It distinguishes itself from siblings like get_meta_connect_status and connect_google by focusing on status rather than mutation or setup.

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

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

It gives clear context for when to use the tool: to determine where the Google connection stands. It also routes the agent to follow-up actions in specific states (pick_google_account, accept_google_terms, re-check later), but it does not explicitly contrast with get_meta_connect_status or connect_google for when-not cases.

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?

Since readOnlyHint and destructiveHint already establish safety, the description adds meaningful behavioral context: the complete status vocabulary and what is included when active. It also notes the side-effect actions expected at certain states, going well beyond annotation-only info.

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 meaning and then packs each status value with its required follow-up in a tightly structured way. No sentence is wasted.

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

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

For a zero-parameter read-only status tool, the description fully covers the return semantics and the actionable next steps for states that need them. The lack of an output schema is mitigated by the inline enumeration of result states and their meaning.

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 is empty with no parameters, so there is no parameter semantics to document beyond the baseline. The description's status branching compensates by explaining how the returned state drives subsequent tool selection.

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 specifically what is being checked ('Where the Meta connection stands') and enumerates the possible statuses, so an agent can distinguish this from get_google_connect_status and connect_meta. It is a clear status-query verb-plus-resource definition.

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 explicit conditional guidance: in selecting_business call pick_meta_business, in selecting_catalog call pick_meta_catalog, and in not_admin reconnect with the correct account. This tells the agent both when to use the tool and what action to take based on the result.

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 the tool as read-only and non-destructive. The description adds useful behavioral context: it returns benchmarks aggregated from Hive's cross-merchant data and compares them to the merchant's own catalog stats.

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 filler. The core purpose is stated first and the usage cue is front-loaded immediately after, making it easy for an agent to scan and act.

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

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

For a simple read-only tool with one optional parameter, the description plus schema fully cover what the tool doesaine and when to invoke it. The absence of an output schema is acceptable because the description names the expected comparison content.

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

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

The schema covers the single optional 'category' parameter completely, including valid values and the default behavior when omitted. The description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The description names a specific verb ('Fetch') and a distinct resource ('Hive cross-merchant signal... category benchmarks... alongside merchant's own catalog stats'), clearly distinguishing it from sibling tools like get_account_summary or get_deep_audit. The comparison purpose is explicit.

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

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

The description provides an explicit trigger condition: 'Use when the user asks

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, and the description does not contradict them. It adds useful scope context—live sync, enrichment progress, and writeback—but does not disclose additional behavioral traits such as latency, staleness, or authorization requirements. The annotation coverage makes this acceptable but not exceptional.

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 focused sentences: the first front-loads the action, resource, and scope, and the second provides practical usage examples. There is no redundant wording or repetition of annotation or schema data.

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

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

For a no-parameter, read-only tool with no output schema, the description is complete enough: it specifies what the tool reads, what components are covered, and when to call it. The agent can invoke it correctly without needing additional clarification.

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 and schema description coverage is 100%, so there is no parameter ambiguity for the agent. The description is not required to explain parameters and does not need to compensate for missing schema documentation.

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

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

The description states a specific verb and resource: 'Read live pipeline status for the merchant's shop' and enumerates the exact pipeline components (sync, enrichment with progress, writeback). It is clearly distinct from sibling status tools like get_google_connect_status and get_meta_connect_status, which focus on connection state rather than overall pipeline progress.

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 example triggering queries: 'is anything running?' or 'how far along is enrichment?' This tells the agent when to use the tool. It does not name sibling alternatives or state when not to use it, but the tool's narrow scope makes the examples sufficient.

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 clear. The description adds valuable context about the response structure, listing what the enriched detail includes. It does not contradict annotations and provides additional behavioral information about the output content.

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 immediately states the tool's purpose and then lists its output contents. There is zero waste, and every element adds value. It is concise 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 simple get-by-ID tool with one parameter and no output schema, the description covers everything an agent needs: what it does, what it returns, and that it targets a specific product. 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?

Schema description coverage is 100%, so the parameter productId is fully documented in the schema. The description merely mentions 'by ID' without adding syntax, format, or constraints beyond the schema. Baseline 3 applies because the schema handles the parameter documentation.

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

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

The description uses a specific verb ('Fetch') with a clear resource ('one product by ID') and lists the exact contents returned ('structured facts, agent description, missing attributes, cultural references, score breakdown'). This clearly distinguishes it from sibling tools like list_products (which lists many) and enrich_product (which likely enriches data), so an agent can identify it immediately.

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: you need full enriched details for a single product. However, it does not explicitly state when to use this tool over alternatives, nor mention any exclusions. There is no reference to list_products for browsing or enrich_product for enrichment. The usage is implied but not explicit.

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

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

Annotations already mark this read-only and non-destructive; the description adds scope by explaining these are manual merchant-side steps and that each section tells the user what to do and why. This goes beyond the structured 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 front-load the core resource ('merchant-side setup steps Pollen cannot do via API') and then give concrete examples and a usage trigger. No filler or redundant restatement.

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 no-parameter, read-only information tool with strong annotations, the description is complete: it defines scope, content style, and when to call it. No output schema exists, but the description adequately characterizes what the returned instructions contain.

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 and the schema fully documents that fact, so parameter semantics are inherently well-covered. The description reinforces that the tool returns instructional content rather than requiring input.

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: getting merchant-side setup steps that Pollen cannot perform via API. It names concrete items like platform plugin/extension activation and surface connections, making it easy to distinguish from sibling status and audit 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 explicitly says to use the tool 'when onboarding or when the user asks what's left to set up?'. It does not explicitly name alternatives or exclusion conditions, but the 'cannot do via API' framing clarifies the boundary between this tool and API-driven setup operations.

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 description only needs to add extra behavioral context. The claim 'Returns up to 50 per call' essentially restates the limit maximum already present in the schema; it adds little beyond that, and no auth, pagination, or side-effect information is provided. No contradiction 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 sentences that are front-loaded with the core purpose, followed by concrete examples, and then the pagination limit. Every word earns its place with no 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 list tool with four optional parameters and no output schema, the description covers the essential actions, filter hints, and maximum returned items. It leaves sorting options and the response structure implicit, but for the tool's low complexity this is acceptable and not a significant 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?

Only 50% of parameters have schema descriptions (search and enrichmentStatus). The description mentions 'optional filters' generically without elaborating on sortBy meanings or enrichmentStatus values beyond the schema enums. Since the schema leaves half the parameters undocumented and the description doesn't compensate, a score below baseline is warranted.

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), resource (products), scope (merchant's catalog), and optional filters. The example queries ('products that haven't been enriched yet', 'products with lowest scores') make the intent unmistakable and naturally differentiate it from get_product, which retrieves a single product.

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?

Concrete example use cases are given ('show me products that haven't been enriched yet' or 'find products with the lowest scores'), which signal when this tool is appropriate. However, it does not explicitly state when not to use it or mention alternatives like get_product for single-product lookups, so it falls short of a perfect 5.

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

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

Annotations provide only readOnlyHint=false and destructiveHint=false, so the description does the work of explaining side effects. It discloses that on success Pollen finishes the handshake and publishes the catalog automatically, which is meaningful behavioral context beyond the annotations. It does not describe failure modes, but the key side effect is covered.

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 sentences with no filler. It front-loads the precondition and action, then immediately specifies the parameter source and success behavior. Every sentence earns its place.

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

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

For a simple, single-parameter tool with no output schema, this description covers the necessary context: when to call it, where the parameter comes from, and what happens on success. No critical operational detail is missing for an agent to select and 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 coverage is 100%, so the baseline is 3. The description adds value by specifying that accountId must be one of the candidates returned by get_google_connect_status, which is not fully captured in the schema's standalone description. This helps the agent resolve the parameter in the correct context.

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 (resume), the resource (Google connect paused on the account picker), and the trigger condition (status selecting_account). It clearly distinguishes itself from sibling tools by referencing the paused state and the candidate source from get_google_connect_status.

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

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

Explicitly states when to use the tool: when a Google connect is paused on the account picker with status selecting_account. It also tells the agent exactly where to obtain the required input (candidates returned by get_google_connect_status), effectively guiding the agent away from guessing or using unrelated connection 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 not read-only and not destructive, so the description doesn't need to restate that. The description adds useful behavioral context: it can advance the flow to the catalog picker or go straight to active, and it resumes a paused state. It doesn't mention side effects like whether the previous selection is overwritten, but the state transition info is valuable and goes 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?

Three sentences, each earning its place: what the tool does, where the input comes from, and what the possible outcomes are. No fluff, no repetition of the title or schema. The most important 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 single-parameter state-transition tool with no output schema, the description covers the essential context: the paused state, the input source, and the possible next states. It could mention what happens if the businessId is invalid or what the response looks like, but given the simplicity of the tool and the annotations, the description is largely 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 coverage is 100% and the single parameter businessId is already described as 'Business portfolio ID from the candidates list'. The description reinforces this by saying to pass the businessId of a candidate from get_meta_connect_status, which adds provenance context beyond the schema. With only one parameter and full schema coverage, the description adds meaningful but not extensive extra value.

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

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

The description states a specific verb ('Resume'), a specific resource ('a Meta connect paused on the business picker'), and the exact status context ('selecting_business'). It also names the required input (businessId) and the possible next states, which clearly distinguishes it from siblings like pick_meta_catalog and pick_google_account.

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 explicitly says when to use this tool: when a Meta connect is paused on the business picker (status selecting_business). It also tells the agent to pass a businessId from get_meta_connect_status, which is a clear prerequisite and source of the parameter. This is strong guidance for an agent deciding between this and sibling 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 only declare readOnlyHint=false and destructiveHint=false, which provide limited safety context. The description adds valuable behavioral insight: picking an existing catalog will cause Pollen to manage (add/remove) products in it, and creating with '__create__' will generate a dedicated catalog. This goes beyond the annotations and informs the agent of 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?

Two sentences, no filler. The core action and status are front-loaded, and the critical safety constraint is delivered in the second sentence. Every word earns its place.

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

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

For a single-param tool with full schema coverage and no output schema, this description covers when to use, how to use, parameter semantics, and a key safety rule. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with a clear description for catalogId. The tool description adds deeper semantics: it explains that '__create__' triggers creation of a catalog named 'Pollen - {shop}', and that the id must come from the candidates list. This enriches the parameter meaning beyond the schema's basic 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 ('Resume') with a precise resource ('Meta connect paused on the catalog picker') and names the action (pass a catalog id or '__create__'). It clearly distinguishes this tool from the sibling 'pick_meta_business' by focusing on the catalog step in the Meta connection flow.

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 explicitly states when to use: when the connection is in 'selecting_catalog' status. It also provides a strong exclusionary guideline ('NEVER pick an existing catalog without the merchant's explicit confirmation'), which is critical for safe usage. It doesn't name explicit alternatives, but the context and caution make usage 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 annotations already indicate this is not read-only and not destructive. The description adds useful behavioral context beyond the annotations by stating that the change only affects future runs, signaling that existing enrichment outputs are not modified.

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

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

Two tight sentences with no unnecessary detail. The core action is first, followed immediately by the most important behavioral caveat, so every sentence earns its place.

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

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

For a simple one-parameter setter, the description captures what is being setchers, why it matters, and the temporal scope of the change. The lack of an output schema is acceptable here since the operation is a straightforward configuration update and no additional workflow prerequisites are apparent.

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

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

Schema description coverage is 100%, and the description's mention of 'used for enrichment' adds only mild context to the provider parameter. The schema already provides the enum values and the basic explanation, so the description does not substantially improve parameter understanding.

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 ('LLM provider'), and further clarifies that the provider is used for enrichment. This differentiates it from the enrichment, catalog, and connection sibling tools with no 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?

Provides clear context by specifying that the effect applies only to future runs, which tells the agent that this is a forward-looking configuration and will not retroactively alter past enrichment. It does not explicitly mention alternatives or exclusion conditions, but no direct alternative exists among the siblings.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the core safety profile is covered. The description adds that the sync is 'full' and pulls from specified platforms, but it does not disclose side effects, rate limits, whether it overwrites existing data, or what happens on failure. This is moderate added value 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?

Two sentences with no redundancy. The first sentence front-loads the action and scope; the second adds a crisp usage condition. Every word earns its place.

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

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

For a zero-parameter trigger tool with no output schema, the description provides the essential purpose and usage context. It does not mention what the trigger returns or how to verify completion, but sibling tools like get_pipeline_status likely fill that gap, so this is a minor omission.

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 and the schema covers everything, so the baseline is 4. The description's mention of 'full product sync' and the source platforms implicitly scopes the operation, but no parameter-level elaboration 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 states a specific verb ('Trigger'), resource ('a full product sync'), and destination ('into Pollen'), and names source platforms. It clearly distinguishes this from enrichment and write-back siblings by adding 'Use before enrichment if products are missing or out of date.'

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 explicit context for when to use the tool ('before enrichment if products are missing or out of date'), which is strong guidance. However, it does not name alternative tools or provide any 'when not to use' exclusions, so it stops short of a fully explicit routing instruction.

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 mark destructiveHint=true, and the description adds meaningful context on top: writes go to the store, sku/barcode/weight are per-variant so variantId is required for multi-variant products, batch calls are capped at 25 updates, and each update returns previous and applied values plus the product's new score. This goes beyond the bare annotation without contradicting it.

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

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

Four sentences with no filler: purpose, usage trigger, per-variant constraint, and batch/return behavior are all packed tightly. The most important discriminator ('merchant-supplied physical facts') is front-loaded, and every clause adds operational 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 mutation tool with one nested-array parameter and no output schema, the description covers the essential operational details: what is written, when to use it, the variantId requirement, the 25-item limit, and what the response returns. It does not cover error conditions or ordering guarantees, but those are not critical for selecting and invoking this 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 parameter-meaning burden. It explains the domain purpose of sku, barcode, weight, and brand, clarifies that these are per-variant when variantId is needed, and notes the max of 25 items. It does not deeply explain weightUnit or the shape of each update object, but the schema provides some nested property descriptions and the description compensates for the main 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 opens with a specific action and resource: 'Write merchant-supplied physical facts to the store', then enumerates the exact fields (SKU, barcode, weight, brand). It also distinguishes the tool from enrichment-based siblings by calling these the gaps Pollen cannot fill, so an agent can reliably tell it apart from enrich_product or enrich_all_products.

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

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

It gives an explicit trigger: 'Use when the merchant provides values', with concrete examples like 'all tees weigh 180 grams' and 'barcodes from my supplier sheet'. This clearly states when the tool is appropriate. It implies the counterpart (do not use when enrichment can supply the data) but does not explicitly name an alternative sibling or say 'do not use for enrichment-derived values', so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate that this is a write. It adds useful context—data goes back as metafields/meta_data and should occur after enrichment—but it does not disclose prerequisites like store connection or whether existing metafields are overwritten.

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

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

The description is three short sentences, each adding distinct value: what the tool does, when to run it, and what user phrases should trigger it. It is front-loaded and free of filler.

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

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

For a zero-parameter tool with no output schema, the description covers the core invocation requirements: the action, the target format, the timing, and trigger phrases. It is slightly light on preconditions like connection/auth, but the sibling connect_* tools and annotations make that gap minor.

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

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

There are no parameters in the input schema, so there are no parameter descriptions to supplement. The tool's behavior is fully represented by the action and target format described, making the schema coverage complete and the baseline of 4 appropriate.

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

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

The description states a specific action ('Push enriched data back') and a specific resource ('the merchant's platform as metafields/meta_data'). It clearly conveys that this is a write/publish operation, though it does not explicitly contrast with siblings like sync_catalog or update_product_facts.

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 usage context: 'Run after enrichment completes' and provides recognized trigger phrases ('publish' or 'push to my store'). It does not mention exclusions or alternatives, but the usage timing and trigger language are clear enough.

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