mcp-server

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

Annotations already mark readOnly/destructive false, but the description goes well beyond: explains productsRefreshing/productsSubmitting as wait signals, warns that productStats and dataCheckErrors are stale mid-refresh, defines isOverlimit/upgradeUrl, and covers terminal failed state plus retryAfterSeconds/rescheduled 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?

Front-loaded with purpose, but the body is a dense run-on paragraph with a corrupted sentence and a stray 'list_ads.' fragment. The information is valuable but would benefit from splitting the export-wait and category-warmup concerns into distinct, clearly structured sections.

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

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

Covers the return shape (no output schema exists), field meanings, polling/wait conditions, stale-data warning, terminal failure handling, and sibling-tool routing. It only loses a point for the unclear ad_id sourcing and the jumbled warmup sentence, which leave minor ambiguity in an otherwise thorough definition.

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 coverage, the description must explain the parameters. It does clearly explain project_id optionality (inferred vs required, list_projects), but the ad_id explanation is garbled — 'ad_id is the id from categoryAttributeWarmup is the OTHER wait' — so it never cleanly states where ad_id comes from.

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?

Opens with a precise verb+resource: 'Get the live run status of one ad: readiness, connection, and product counts.' It explicitly scopes ads vs marketplaces and later contrasts with get_ad and get_ad_report, so an agent can distinguish it from 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?

States exact usage: 'Use ad_status for run progress and get_ad for configuration/mapping. For the detailed error breakdown use get_ad_report.' It also gives the waiting/polling scenario after exports and the project_id_required fallback to list_projects.

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 signal this is a non-read-only, non-destructive mutation. The description adds meaningful behavior beyond those hints: it creates a new ad copy, has no order sync, and returns a specific payload where integrationId belongs to the new clone. It does not detail every possible side effect, but the annotation coverage lowers the burden and the description handles the essentials.

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

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

Three dense sentences, with the core action front-loaded in the first sentence. The return payload and parameter semantics are packed into the final sentence without redundancy. Every sentence earns its place and no space 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 two-parameter clone operation with no output schema, the description covers purpose, scope versus marketplaces, both parameters, conditional project_id handling, and the exact return payload. The only minor omission is explicitly naming clone_marketplace as the alternative, but the marketplace exclusion is already stated.

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 full responsibility for explaining parameters. It clearly identifies ad_id as the source ad from list_ads and explains project_id's optionality with the conditional requirement to call list_projects. This fully compensates for the schema's lack of 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 opens with the specific action 'Clone an ad' and defines it as creating a copy of settings and configuration as a new ad. It explicitly distinguishes ads from marketplaces, which differentiates this tool from clone_marketplace and create_ad without requiring the agent to inspect schemas.

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

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

The description says ad_id comes from list_ads and explains when project_id is optional versus when the agent should call list_projects. It implicitly excludes marketplaces by stating ads are not marketplaces, though it does not explicitly name clone_marketplace as the alternative tool.

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

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

Annotations only state readOnlyHint=false and destructiveHint=false, so the description must disclose side effects. It clearly states that a copy is created (a mutating action) and describes the exact return payload, including that integrationId refers to the NEW clone. This goes beyond the annotations by specifying output structure and confirming the clone is a separate entity. It does not contradict any annotations, so a 4 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, dense sentence followed by a clear return specification. It front-loads the core purpose and then packs parameter guidance and return details without waste. While it is longer than minimal, every clause earns its place – no redundancy. It could be slightly more concise, but 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 covers the essential information an agent needs: what it does, what parameters are required and how to source them, the return value structure, and the distinction between the original and the clone. It also indicates the action type ('clone') and status ('cloned') in the output. Given there is no output schema, this description serves as the complete contract for the operation. Nothing critical 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 both parameters: marketplace_id is the source (referencing list_marketplaces) and project_id is optional with conditions (inferred for single-project customers, otherwise required and must be obtained from list_projects). This adds significant meaning beyond the bare integer schema, giving the agent enough to supply correct values. This is excellent 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 ('clone'), a specific resource ('marketplace'), and clarifies what is copied ('settings and configuration'). It distinguishes itself from create_marketplace (which creates from scratch) by explicitly stating it makes a copy of an existing marketplace, and the required source field is clearly identified. This leaves no ambiguity about the tool's purpose.

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 practical usage context: marketplace_id is the source from list_marketplaces, and project_id is optional or required depending on the customer's project setup, with a pointer to list_projects. This tells the agent when and how to call the tool, though it does not explicitly contrast with sibling tools like create_marketplace or delete_marketplace. It provides clear prerequisites and conditional logic, so it earns a 4.

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 are minimal (readOnlyHint false, destructiveHint false), so the description carries the burden — and it over-delivers. It discloses the budget-spending activation side effect of the SUMMARY step, async product export/generation in transitions[], background category-attribute downloads, terminal (non-retryable) oauth/credentials statuses, and the reject-list of unsettable flags. It also corrects a plausible misreading of destructiveHint=false by warning that AUTO mode publishes to the LIVE channel and spends budget. No contradiction with annotations, which simply understate this risk.

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 long, but nearly every sentence carries unique operational information for a genuinely complex tool with heterogeneous step types, async transitions, and deferred attribute loading. It is front-loaded with the critical activation warning and ordering rule before payload details. Minor redundancy exists — the non-configurability of the connection step and the do-not-retry instruction are stated two or three times — which costs it full marks but is arguably intentional emphasis.

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

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

There is no output schema, so the description correctly documents the return shape ({integrationId, stepType, status, ready, lastStep, nextStepType, oauthUrl, transitions[], message}) and explains every status value, the async polling requirements, terminal vs retryable conditions, and the success path. For a tool this complex, nothing an agent needs to call it safely and 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 only 60%, and the description compensates massively. It explains ad_id provenance (list_ads/create_ad), when project_id is required and how to resolve it (list_projects), the step_index vs step_type disambiguation rule, the exact payload shape {items: {fieldCode: value}} with send-only-changed semantics, dropdown value-vs-position rule, optionsPending handling, required-field behavior, and dedicated payloads for the product-filter step (attribute_filter, category_filter, export_out_of_stock) including what gets rejected.

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?

Opens with a specific verb + resource + scope: "Configure ONE step of an ad's setup wizard." The emphasis on "ONE step" and the repeated contrast with ads-based channels ("not marketplaces, and have no order sync") clearly distinguishes it from siblings like configure_marketplace_step, set_ad_product_mode, and set_ad_name without needing to open their schemas.

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

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

Exceptionally explicit about when and when not to use the tool: it names set_ad_product_mode for safe testing, says to poll ad_status instead of calling the refresh tool while attributes warm up, routes state 'failed' to refresh_ad_category_attributes once, and states the connection/auth step "can NEVER be set through MCP." It even prescribes the stop-and-wait user handoff for oauthUrl/editUrl. The description also documents the step-by-step iteration loop terminating at nextStepType null.

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

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

Beyond the annotations, the description discloses major side effects: the summary step activates the marketplace and may publish to the LIVE channel, spending budget; transitions may run async exports; category attributes may download in the background; and connection/auth steps are permanently non-configurable via MCP. It also communicates terminal statuses, error conditions, and what not to retry.

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

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

The description is long, but justified by the tool's complexity and the number of failure modes. Critical safety information is front-loaded, though some redundancy exists around retrying auth steps and out-of-order configuration, which slightly bloats the text.

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

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

Despite having no output schema, the description fully explains the return object's key fields, statuses, async behavior, deferred attribute warmup, and when to poll marketplace_status. It covers prerequisites, error handling, and user-interaction requirements, leaving no obvious gap that would cause an agent to invoke the tool incorrectly.

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

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

Schema coverage is 60%, but the description more than compensates: it explains that payload is built from steps[].fields, that options must be sent by value rather than list position, how to handle optionsPending, and gives exact structured payloads for product-filter, category-filter, and export_out_of_stock. It also clarifies where marketplace_id and project_id come from.

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

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

The description names a specific verb and resource ('Configure ONE step of a marketplace's setup wizard') and immediately distinguishes this tool from related siblings like configure_ad_step and configure_order_connection. It makes the tool's role unmistakable even before reading the schema.

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

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

The description gives explicit when-to-use guidance: call repeatedly in step order, stop when nextStepType is null, use step_index to disambiguate, and never configure connection/auth steps through MCP. It also names alternative tools for safe testing (set_marketplace_product_mode, run_marketplace_item_action) and for handling failed attribute warmup (refresh_marketplace_category_attributes).

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

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

Beyond the annotations (idempotentHint=true, readOnlyHint=false), the description discloses important behavioral traits: exact return shape, success/error statuses ('updated', 'rejected' with HTTP 400, 'prerequisite_not_met' with HTTP 409), the fact that rejected writes save NOTHING, merging behavior for order_config keys, and the guarantee that credentials are never changed. This significantly exceeds what annotations provide.

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 long but every sentence carries essential information: the action, parameter semantics, error behavior, prerequisite flow, merge semantics, and credential boundaries. It is front-loaded with the main purpose and structured logically with 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?

Given no output schema, the description fully covers return values and error conditions. It also covers prerequisites, how to obtain required IDs, what happens on partial failure, and where to route for missing project_id. There are no obvious gaps an agent would need filled to invoke 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?

The schema already has 80% description coverage, and the tool description adds further meaning: it explains that order_config uses codes from get_order_connection.orderConfigFields, that order_sync_level is restricted to two values, that order_status toggles syncing on/off, and that order_config keys are merged rather than replaced. It also clarifies the source of connection_id and the optional/required nature of project_id.

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 ('Set a standalone order connection's Orders Config, sync level and on/off state') with a clear resource and scope. It explicitly distinguishes itself from sibling tools by noting that marketplace credentials are NEVER set via MCP, so an agent can tell it apart from configure_marketplace_step or enable_marketplace_order_sync.

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 when-to-use and when-not-to-use guidance: it is for order settings only, not marketplace credentials; it can only enable connections after authentication is completed via the Koongo UI and test_order_connection; and it directs the agent to list_projects when project_id is required. This is strong routing relative to 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?

The description thoroughly discloses the return shape, including integrationId, action, status, kind, editUrl, nextStepType, and message. It also explains the 'created' vs 'prerequisite_not_met' statuses, the HTTP 409 case, and that the returned integrationId is the ad_id used by get_ad and configure_ad_step.

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 long but well organized, moving from channel eligibility to response semantics to each parameter in schema order. Nearly every sentence earns its place, though a few asides like the upgrade-link reference add marginal value and prevent it from being maximally concise.

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 lack of an output schema and the five-parameter surface, the description is operationally complete. It covers return fields, status handling, prerequisite failures, the project_id inference edge case, and the relationship between the returned integrationId and subsequent ad tooling.

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?

Although the schema already covers 80% of parameters, the description adds essential meaning: how channel_code is obtained, when definition_code must be omitted, what multichannel_code links, name non-uniqueness, and the project_id fallback via list_projects. It specifically compensates for project_id having no 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 opens with a specific verb and resource: 'Create a new ad for a project from one of the channels in list_ad_channels.' It further distinguishes ads from marketplaces by saying they 'publish products to the ad platform and have no order sync,' so an agent can separate this from marketplace creation 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 context for sourcing channel_code from list_ad_channels and explicitly rules out marketplaces by contrast, including the no-order-sync distinction. It does not explicitly name an alternative tool like create_marketplace, but the behavioral boundary makes the intended usage clear 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?

Despite annotations providing no behavioral hints, the description fully discloses behavior: return fields, optional vs required behavior, downstream mapping requirements, data import prerequisite, and the quota_reached error with upsellUrl. This is far beyond what structured annotations provide and gives the agent everything needed to understand side effects and follow-ups.

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 information-rich, front-loaded with the core purpose before diving into prerequisites, optional behavior, and error handling. It is longer than average but nearly every sentence earns its place; a slightly tighter structure could improve scannability.

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 creation tool with no output schema and only two parameters, this description is exceptionally complete: it names return fields, explains category mapping, attribute mapping, import prerequisites, and quota errors with next steps. An agent can invoke this tool and handle the subsequent workflow without needing additional 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 coverage is 0%, but the description fully compensates: feed_code is constrained to values from list_feed_templates, and project_id is explained as optional with inference rules and the project_id_required error case. Every parameter's semantics are meaningfully described beyond the bare 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 opens with a specific verb and resource: 'Create a Koongo product feed for a project.' This clearly distinguishes it from sibling creation tools like create_ad, create_marketplace, and create_rule, and the rest of the description reinforces that this tool specifically deals with product feeds.

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 strong usage guidance: feed_code must come from list_feed_templates, project_id handling is explained based on customer project count, and it covers prerequisites and error handling. However, it does not explicitly contrast this with update_feed or state when to prefer one over the other.

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

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

Beyond the annotations, the description fully discloses behavioral details: status can be 'created' or 'prerequisite_not_met' with HTTP 409 semantics, the message can explain required prerequisites and upgrade links, and the definition_code/versionType behavior is clarified. It also explains optional project_id inference and the distinction between primary_sync and versionType, which the annotations alone would not convey.

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

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

The description is long and dense, but every clause carries operational detail and the core purpose is front-loaded. Some parenthetical interruptions and repeated clarifications make it read as a wall of text, so bullet structure could improve scannability, but there is no filler language.

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 seven parameters, one required field, no output schema, and sparse annotations, the description is unusually complete: it covers return fields, status semantics, prerequisite handling, upgrade links, next-step routing, optional parameters, and how to resolve missing project_id. An agent has almost everything 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?

Although schema description coverage is 86%, the description adds substantial meaning: it ties channel_code directly to list_marketplace_channels, explains how definition_code is sourced and when to omit it, disambiguates primary_sync from versionType, describes name uniqueness and rename behavior, and explains project_id inference. These additions go well beyond the schema descriptions, especially for project_id, which has no 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 opens with a specific verb–resource pair: 'Create a new marketplace integration for a project,' and immediately scopes the channel source to list_marketplace_channels. It also clarifies exactly what is created and what the expected status outcomes are, distinguishing it from sibling create tools like create_ad and create_feed. The return shape and follow-up flow make the tool's role unmistakable.

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 strong workflow guidance: where to get channel_code, where to get definition_code, when to call list_projects, and how to proceed with configure_marketplace_step after creation. It does not explicitly state when not to use this tool versus alternatives like clone_marketplace or configure_marketplace_step, so it stops just 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 indicate mutability and open-world behavior, but the description adds crucial behavioral detail beyond them: the tool returns an authUrl for the user, does not handle credentials, can return 'auth_required' or 'rejected', may raise the monthly bill, and may require a plan upgrade. This is exactly the kind of side-effect and workflow context an agent needs and the structured fields do not provide.

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 long, but every sentence carries decision-critical information: what the tool does, what it does not do, user action required, return shape, cost consequences, plan upgrade possibility, and post-auth workflow. It is front-loaded with the most important trait (no credential handling) immediately after the purpose statement. Slightly dense, but justifiably so.

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 there is no output schema, the description remarkably covers the return object's key fields, possible statuses, cost impact semantics, the upsell/plan-upgrade case, and the expected next steps after authentication. An agent has enough information to call the tool correctly, interpret its response, and avoid a costly or dangerous action.

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

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

Schema coverage is only 50%, so the description must compensate for the undocumented project_id parameter. It does so by explaining project_id is optional and that list_projects should be called when it is required. It also reinforces channel_api_code's origin from list_order_channels, adding practical sourcing meaning beyond the schema text.

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

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

The description opens with a specific verb and resource: 'Start adding a standalone order connection for a channel from list_order_channels.' It clearly distinguishes itself from related siblings by emphasizing that it does NOT create or authenticate the connection itself, but returns a user-facing Koongo UI link. This makes the tool's role unambiguous even without opening the schema.

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

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

The description gives clear context for when to use the tool: when starting a standalone order connection, and it explicitly instructs that the assistant must not handle credentials and must get user confirmation before opening the link when costImpact.willIncrease is true. It also names the project_id-required fallback (call list_projects) and the follow-up tools (test_order_connection, configure_order_connection), though it does not formally state exclusions versus all 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 only state readOnlyHint/idempotentHint/destructiveHint all false; the description adds substantial behavioral context: rules write nothing onto products, included _id/id is ignored, the server always mints a new id, the tool never overwrites, invalid rules return HTTP 200 with status 'rejected', and new rules have no feed effect until attached and exported. 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?

Long, but appropriately so for a complex creation tool with many failure modes. It is front-loaded with purpose and guardrail, uses labeled sections (GUARDRAIL, SAVE-ONLY, VALUE/OPTIONS MAPPING), and every block addresses a distinct pitfall an agent would otherwise hit. Dense and structured rather than padded.

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

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

There is no output schema, so the description carries the return contract: {ruleId, scope, status, changed, reason, validation}. It also covers project_id inference, dry-run limitations, value mapping array semantics, and post-create attachment workflow. An agent has everything needed to invoke this tool correctly and avoid common mistakes.

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

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

Schema description coverage is only 33%, but the description compensates fully. It supplies the complete nested rule document shape, explains that scope has 'project' as default and the shared_template behavior including template_read_only error, and clarifies project_id is optional/inferred unless required. This goes well beyond the sparse 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?

Opens with a specific verb and resource: 'Create a NEW product rule (an Attribute Rule).' It is clearly distinguished from siblings like update_rule, delete_rule, and validate_rule by explicitly saying edits use update_rule and validation is a prerequisite. The purpose is unmistakable.

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 emphatic when-not-to-use guidance: do not create a Rule for complex per-product enrichment; use set_api_source/set_ai_source instead; validate_rule first; use map_feed_attribute/export_feed to give it effect; use update_rule for edits. Alternatives and exclusions are explicit 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?

The description goes well beyond the annotations: it discloses that deletion stops syncing, removes the ad from the list, hard-deletes the ad's feeds/channel profiles, and has no restore tool. It also explains the HTTP 400 error when confirm is missing and specifies the exact return payload. This is unusually transparent for a destructive tool.

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

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

The description is dense but every clause earns its place. It front-loads the destructive warning, then covers confirmation behavior, scope of deletion, return value, and parameter provenance in a tight sequence. 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 destructive, multi-effect mutation with a confirmation guard, the description covers the essential context: what is deleted, what is not affected (no order sync), what happens without confirmation, how to get required IDs, and the expected return. There is no output schema, so the return shape description is necessary and 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It does: ad_id is sourced from list_ads, confirm must be true to execute, and project_id is optional/inferred unless project_id_required, in which case list_projects is the prerequisite. This fully compensates for the bare schema.

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

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

The description states a precise verb and resource ('Delete an ad') and immediately differentiates ads from marketplaces: 'Ads are ads-based channels ... not marketplaces: they publish products to the ad platform and have no order sync.' This clearly distinguishes it from sibling tools like delete_marketplace and delete_feed.

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

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

Usage guidance is explicit and actionable: confirm with the user first, call with confirm:true, warn that deletion cannot be undone. It also gives the failure mode ('Without confirm:true the call returns error confirm_required') and instructs when to call list_projects for project_id. No inference is left to the agent.

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

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

Annotations already carry destructiveHint=true and idempotentHint=true, but the description adds crucial context: custom_<code> values are not immediately erased but clear on the next full product import; the addon requirement (without it returns 403 with addonCode+upsellUrl, and instructs to show the upsellUrl and not retry); and the exact return shape. This significantly enriches the behavioral profile 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 compact and front-loaded: the primary action and purpose appear in the first sentence. Supporting notes (delay, addon, return) follow logically without redundancy. Every sentence adds value; 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 destructive, idempotent mutation with an optional parameter and a prerequisite addon, the description covers all necessary aspects: what is deleted, when it takes effect, how to re-import, optional parameter behavior, the error condition and required response, and the return contract (including both statuses and the applied field). 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?

Schema coverage is 0%, so the description must explain parameters. It does: code is the identifier ('by code'), apply is explained ('set apply:true to re-import now'), and project_id is noted as optional and inferred for single-project customers. All three parameters receive meaningful explanation, fully compensating for the schema gap.

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

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

States the verb 'Remove' and the resource 'AI source (its CSV + registration)' and identifies the key 'code'. It clearly distinguishes this from delete_api_source or delete_feed by naming the resource type, so an agent can pick the correct deletion 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?

The description clarifies the effect ('so it is no longer applied on future imports') and the option to re-import with apply:true. It does not explicitly name alternatives or state when to prefer this over delete_api_source, but the resource type is unambiguous. Context is clear; exclusions are not stated.

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

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

The description adds significant side-effect context beyond the destructiveHint annotation: removal applies to every product, is immediate only when apply is true, otherwise clears on next import, and is guarded by an addon requirement with exact error fields. It also states the return shape, so the agent knows what success looks like.

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

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

Two sentences front-load the primary action and then pack optional behavior, addon error handling, and response format without redundancy. 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?

The description covers parameters, behavior, error handling, and return shape, which is strong given there is no output schema. It leaves a small ambiguity around whether project_id is required for multi-project customers and does not state behavior when code is absent, so it is not fully complete.

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

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

Schema description coverage is 0%, yet the description explains all three parameters: code (the attribute identifier), apply (controls immediate versus next-import clearing), and project_id (optional, inferred for single-project customers). This fully compensates for the schema's lack of parameter 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 opens with 'Remove an API source attribute by `code` from every product so it is no longer applied', naming the verb, resource, and scope. This clearly distinguishes it from set_api_source (set vs remove), list_api_sources (list vs delete), and delete_ai_source (API vs AI).

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 tells the agent when to set apply:true (re-import now) versus letting it clear on the next import, and when to stop by showing the upsellUrl and not retrying on addon_required. project_id inference is also covered, but the description never names sibling alternatives or an explicit do-not-use condition, 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?

Beyond annotations, it discloses soft-delete behavior, the confirm guard and its exact error/HTTP status, that nothing is deleted without confirmation, the return shape, and recoverability via restore_feed. This is rich behavioral context that annotations alone do not provide, and it does not contradict any annotation.

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

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

Four dense, purpose-driven sentences with the destructive warning front-loaded. Every sentence adds operational value: semantics, confirmation requirement, error behavior, return value, and parameter provenance.

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 3-param, no-output-schema tool, the description covers input semantics, required confirmation, error behavior, return value, and recovery path. An agent has everything needed to invoke it safely and 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 0%, so the description carries the burden. It explains confirm:true as required for deletion, identifies feed_id's source, and marks project_id as optional. It does not explain project_id's role further, but all three params receive at least meaningful semantic 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 clearly states 'Delete a feed' with specific soft-delete semantics, and explicitly references restore_feed, distinguishing it from other delete_* siblings. The resource and action 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?

It gives explicit operational guidance: confirm with the user first, pass confirm:true, and notes the error without it. It also tells the agent where feed_id comes from. It doesn't deeply contrast with alternatives, but the restore_feed mention and deletion context make the guidance clear.

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

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

Goes far beyond the annotations: it details the full cascade of side effects (stops syncing, removes from list, hard-deletes feeds/channel profiles, unregisters webhooks), states irreversibility, and explains the confirm_required error path. No contradiction with the destructiveHint or readOnlyHint annotations is present.

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 but every sentence earns its place: warning, side effects, confirmation requirement, error behavior, return shape, and parameter sourcing. The destructive warning is front-loaded, and the text remains readable despite covering multiple consequential 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?

For a destructive tool with no output schema, the description provides complete operational context: return value shape, error condition, side effects, irreversibility warning, and parameter prerequisites. An agent has everything needed to invoke it correctly and safely.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It clearly explains confirm (must be true), marketplace_id (from list_marketplaces), and project_id (optional/inferred vs. required depending on customer type). This fully compensates for the schema gap.

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

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

States the specific verb ('Delete') and resource ('marketplace'), clearly differentiating it from create/pause/resume/repair siblings. Immediately adds the critical destructive scope, 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?

Provides explicit workflow guidance: warn the user, confirm first, then call with confirm:true; also specifies where marketplace_id comes from and when project_id is required. It does not explicitly name a less-destructive alternative like pause_marketplace, but the confirmation and prerequisites make usage conditions 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?

Beyond annotations that already mark destructiveHint=true, the description discloses the confirm_required guardrail, the unlink behavior, the effect on feeds reverting to another value source, and the return payload shape. It also explains that export_feed should be run on affected feeds, which is important operational context.

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

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

The description is dense but well-structured, front-loading the destructive nature and key prerequisite before scope and project_id details. Every sentence carries real guidance, though the information density makes it slightly longer than strictly necessary.

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 covers prerequisites, error cases, return values, side effects, and required follow-up actions. With no output schema present, it fully explains what the agent should expect and do, leaving no critical gaps for a destructive operation.

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

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

Schema coverage is only 50%; rule_id and project_id lack descriptions in the schema. The description compensates by explaining how to identify the rule via list_rules and by detailing when project_id is optional versus required, adding meaning the schema alone does not provide.

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

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

The description states a specific verb and resource — 'Delete a product rule (Attribute Rule)' — and clearly distinguishes the scope of what happens: the rule is deleted and unlinked from every feed attribute using it. It differentiates from siblings like update_rule by naming the unique destructive behavior and its consequences.

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 when-to-use guidance: check usageCount with list_rules/get_rule first, warn the user, and only call with confirm:true. It also explains the shared_template access error and how to handle missing project_id, providing clear prerequisites and troubleshooting steps.

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

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

Annotations already carry readOnlyHint=true, but the description adds significant behavioral detail: a Rule writes nothing to products, the server reassigns sortId values, casts numeric values on save, and silently accepts mis-typed mapping arrays that result in no mapping. 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?

Although long, the description is dense and every major block (guardrail, returned shapes, condition trees, type matching, mapping gotchas, validation workflow) adds decision-relevant information for a complex tool. It front-loads the core purpose and guardrail before diving into 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 no output schema, the description supplies the complete return contract: operations, conditions, ruleSchema, examples, and the rule document and condition tree shapes. It also covers parameter effects, common failure modes, and the surrounding create/validate workflow, so an agent has what it needs 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%, but the description fully compensates: it explains group filtering, detail 'full' vs 'compact' behavior, include_conditions, and include_examples. It also explains argument spec semantics such as optionsSource, enum options, and array-of-object mapping 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 opens with a specific verb and resource: 'Discover the vocabulary for building a product rule' and defines the domain ('attribute-value transformation'). It clearly separates this from sibling write tools by instructing to call it FIRST before writing a rule.

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 when-to-use guidance: call before create/update/validate and before writing any rule, so only supported operations/conditions/arguments are used. It also names alternatives and exclusions, including enriching products with set_api_source/set_ai_source instead of a Rule, and mandates validate_rule before create_rule/update_rule.

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 idempotentHint:true, but the description adds substantial behavioral context beyond that: it states that the tool adds the order-settings step and leaves syncing OFF, that status can be 'updated' (added or already on) or 'prerequisite_not_met', and that it returns a specific object shape. It also clarifies that it is a capability enabler, not a toggle, which is a non-obvious nuance. The description complements and extends the annotation rather than 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?

The description is dense but every sentence earns its place: it defines the tool, distinguishes it from the mode toggle, explains the prerequisite, outlines the workflow, defines return values, and specifies both parameters. It is organized logically from definition to mechanics to follow-up actions, and it front-loads the core distinction. Length is justified by the tool's complexity; there is 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?

Given the tool's complexity, the absence of an output schema, and the 0% schema coverage, the description covers everything an agent needs: the exact purpose, the precondition, the post-step workflow referencing sibling tools (configure_marketplace_step, set_marketplace_order_mode, list_marketplaces, list_projects), the return object structure, and the domain restriction. 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 input schema has zero description coverage (0%), so the description must carry the full burden for both parameters. It does: it explains that marketplace_id comes from list_marketplaces, and that project_id is optional when the customer has a single project but required otherwise, and to call list_projects if needed. This fully compensates for the schema's silence.

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 precise verb+resource: 'Add ORDER SYNC to an existing marketplace' and immediately distinguishes the capability from the on/off switch, framing it as 'the capability, not the on/off switch.' It explicitly names the alternative tool (set_marketplace_order_mode) and specifies that this tool turns the capability ON for marketplaces created without it. This leaves no ambiguity about what the tool does or how it differs from its siblings.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: only offer it when get_marketplace reports canEnableOrderSync:true, and that otherwise it returns 'prerequisite_not_met' (HTTP 409). It also details the full following workflow: re-fetch get_marketplace, configure the new 'order-settings' step with configure_marketplace_step, then call set_marketplace_order_mode enabled:true. It even explains the marketplaces-only limitation. This is thorough and leaves no inference to the agent.

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

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

Annotations only indicate that this is not read-only; the description adds the important async behavior: status is 'queued' via the export queue and the agent must poll get_feed_status. This is genuinely useful context beyond what annotations convey.

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

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

Three dense sentences cover the action, return shape, async behavior, polling step, and parameter provenance. Every sentence earns its place and key 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 simple two-parameter trigger tool with no output schema, the description is complete: it gives the return fields, status semantics, the required next step, and parameter source. Nothing essential to invoking 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 description coverage is 0%, but the description compensates by explaining that feed_id comes from list_feeds / create_feed and that project_id is optional. It could further explain project_id's purpose, but for two integer parameters this is reasonable.

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: 'Trigger a (re)generation of the feed file.' It clearly identifies the resource and differentiates this tool from read-only siblings by emphasizing the export action and async status response.

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 explicit follow-up guidance: 'poll get_feed_status until status becomes generated.' It also tells the agent where feed_id comes from and that project_id is optional. It does not explicitly name an alternative tool or when-not-to-use conditions, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial context beyond that: activationBehavior semantics, secret handling, connection ownership/health, taxonomy read-only constraints, and the warning that the auth step cannot be configured via MCP. There is no contradiction with 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 front-loaded with the purpose and a CRITICAL warning, which is good, but it is far too long and contains a garbled, broken sentence: 'value is Some field metadata comes from the channel connection and does NOT exist before the auth step is done...' and then 'the current value.' Some important details are present, but the structure makes them harder to parse than necessary.

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

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

With no output schema and a complex nested response, the description compensates thoroughly: it enumerates the full return object, explains the wizard steps, fields, optionsPending semantics, connection/auth restrictions, and how to build configure_ad_step payloads. It is complete enough for an agent to use the tool correctly in its surrounding workflow.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains both parameters explicitly: ad_id comes from list_ads / create_ad, and project_id is optional when inferred for a single-project customer, required otherwise with a pointer to list_projects. This goes well beyond the raw integer types in the schema.

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

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

The opening sentence states a specific verb and resource: 'Get the full detail of one ad: identity + state + the configuration wizard steps.' It clearly distinguishes this from siblings like ad_status, and the later note that ads are not marketplaces further differentiates it from marketplace 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 explicitly says 'Use get_ad for configuration and ad_status for run progress,' directly routing an agent between two similar-looking tools. It also names related tools (configure_ad_step, set_ad_product_mode, test_ad_connection, list_ads, create_ad, list_projects) and explains when project_id is required.

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

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

Annotations only declare readOnlyHint and destructiveHint, so the description adds substantial behavioral value: the categoryAttributeWarmup pending:true provisional-count caveat, the ruleEnabled=false effective-source nuance, the currency double-conversion risk, the 'default is not a decision' trust warning, and the step-vs-override precedence rule. The mention of writing an override refers to map_ad_attribute's behavior, not this tool's, so it does not contradict readOnlyHint.

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

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

Front-loaded with purpose and nearly every clause carries unique, non-redundant information, so the length is largely justified by complexity. However, the definition is one dense unbroken paragraph with two text-merge artifacts — 'ad_id is from Each row also says WHERE its value comes from' and the orphaned 'list_ads.' fragment — that break the reading flow and obscure meaning.

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

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

With no output schema and high complexity (20+ return fields, provisional-state semantics, currency conversion rules), the description carries the full burden and nearly succeeds: it enumerates the return structure, defines the valueSource enum, explains requiredUnmappedCount/unresolvedCodes, and flags the warmup incompleteness. The garbled ad_id provenance sentence and the mid-paragraph burial of the critical warmup warning slightly reduce practical 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?

With only 33% schema description coverage (only only_unresolved documented), the description compensates for all three parameters: ad_id is sourced from list_ads, project_id's optionality plus the project_id_required branch to list_projects, and only_unresolved:true filters to required-unmapped rows. This is full semantic compensation for the coverage gap.

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

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

The opening clause 'List an ad's OUTPUT attributes and how each is currently sourced' names a specific verb, resource, and scope, and the parenthetical 'the tool for SOLVING THE ATTRIBUTE FORM' brands its distinct role among siblings like get_marketplace_attributes, get_attribute_options, and map_ad_attribute. The read-vs-write nature is unambiguous from 'List' and 'Returns'.

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 route guidance: fill attributes via map_ad_attribute, change step-driven fields via configure_ad_step with the warning that mapping writes a permanent override, obtain ad_id from list_ads, call list_projects when project_id_required, and poll ad_status during categoryAttributeWarmup. This is exemplary when/when-not coverage against a large sibling set.

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 goes beyond this by defining the semantic domain (ads vs. marketplaces, no order sync), explaining the meaning of versionType ('primary' vs. 'secondary'), and disclosing that project_id is optional only under a specific condition (single-project customer vs. project_id_required). These are behavioral details the annotations do not convey, making the description genuinely informative.

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 longer than typical but every sentence carries essential information: the what, the domain disambiguation, the return structure, field semantics, and usage callout. It is well-structured: the primary purpose is front-loaded, followed by clarifying context, then parameter guidance. It is not padded with fluff, though it could potentially shorten the return-structure details since there is no output schema and they are necessary for the agent to understand the result.

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 getter, this description is unusually complete. It includes the full return payload shape with nested definitions, clarifies how to interpret versionType, states the exact ordering of use relative to list_ad_channels and create_ad, and covers the project_id edge case. No output schema is provided, so the description must carry the return contract — and it does. An agent has everything needed to invoke 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?

With schema coverage at 50%, only channel_code has a schema description, and it is minimal. The description compensates fully: it explains channel_code's provenance ('from list_ad_channels'), describes project_id's optionality and the exact condition for when it is required, and maps both to their roles in selecting a definitionCode. This adds meaning beyond the schema's bare type constraints.

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 ('Get one ad channel's detail') and immediately narrows scope to 'integration TYPES it supports and each type's capabilities.' It explicitly differentiates ad channels from marketplaces ('Ads are ads-based channels... not marketplaces') and names the sibling tools it is not (list_ad_channels, create_ad). This leaves no ambiguity about what the tool does and how it differs from get_marketplace_channel.

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 when-to-use guidance: 'Call this before create_ad to choose the right definitionCode for the channel.' It also specifies where input comes from ('channel_code is the channelCode from list_ad_channels') and when the optional project_id is needed (project_id_required otherwise — then call list_projects and pass its project_id). This is direct operational guidance that an agent can act on without inference.

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

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

Beyond the readOnly/openWorld/destructive annotations, it discloses ordering ('newest first'), content type ('process metadata only, no raw product values'), empty-result behavior, and the raw-vs-label distinction. This is rich, non-redundant behavioral context.

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

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

The description is long but every sentence carries signal: purpose, return shape, label semantics, empty behavior, id provenance, and optionality. The main use is front-loaded and the details are organized from most to least important.

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

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

With no output schema, it supplies the exact return shape and field semantics for the human-readable labels, which is sufficient for an agent to interpret results. Inputs are fully covered by the schema plus the added id and optionality context. No critical behavioral gap remains.

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 already documents ad_id, item_id, and limit; the description adds the cross-tool provenance ('same id get_ad_item_report uses') and the optional/required project_id branch. It also clarifies ad_id is the integrationId from list_ads, closing the one gap left by the schema.

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

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

The description names the exact resource ('ONE ad listing item's action-log timeline') and the diagnostic intent ('explain WHY an item ended in its current state'). It clearly differentiates from get_ad_item_report by stating it uses the same item_id and is meant to be paired with it, not confused with it.

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

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

It gives the intended use case (diagnosing a failing product), source-tool relationships (item_id from list_ad_items, ad_id from list_ads), and conditional project_id routing ('call list_projects'). It does not explicitly say when not to use it or mention the analogous marketplace-history sibling, so it stops short of a full when/when-not statement.

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 readOnly/destructive annotations, it discloses the sensitiveGate behavior (currentValue withheld until acknowledge_sensitive:true is sent), the meaning of error sources ('export = Koongo-side validation... adapter / api_error = channel-side reject'), and raw versus human-readable field semantics. This is substantial behavioral context with no contradiction to 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 long but dense and front-loaded: the first sentence states purpose and the full output shape, then each clause explains a distinct aspect such as human vs raw codes, error source/severity, sensitive gate, and ID provenance. There is no filler or repetition of annotations.

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

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

Despite having no output schema, the description enumerates the report shape and the semantics of its key fields, including the nested errors array and sensitiveGate. It covers ID sourcing, project_id error handling, and the two-step sensitive-data retrieval, so an agent has enough context to invoke 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 coverage is 75%, and the description compensates fully: item_id/ad_id origins are pinned to source calls, project_id's optionality and fallback are explained (project_id has no schema description), and acknowledge_sensitive is tied to the sensitiveGate flow. It adds clear meaning beyond the input 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 clearly states a specific action and resource: 'Get the full error report of ONE ad listing item,' with the purpose 'why the product passed/failed.' The scope is clear enough to distinguish from ad-level reports, though it does not explicitly name sibling tools like get_ad_report or get_ad_item_history.

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 usage context: per-item error reports, ID provenance ('item_id is the itemId from list_ad_items', 'ad_id is the integrationId from list_ads'), and a fallback ('project_id is OPTIONAL (project_id_required otherwise — then call list_projects)'). It also explains the two-call sensitive-data flow. It does not explicitly contrast with aggregate or history siblings, but the context is clear.

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

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds significant behavioral nuance: the split between dataCheckErrors (pre-submission koongo data check) and channelErrors (post-submission channel responses), the combined totals in errorCount/warningCount, and the async generation prerequisite. It also explains the source field values ('export' vs 'adapter'/'api_error') and the meaning of statusCounts vs listingStatusCounts. This goes well beyond the annotations and fully discloses report 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 long but dense: every sentence adds distinct information, from return shape to async behavior to field semantics. The opening sentence immediately states purpose, satisfying front-loading. It could be slightly better structured (e.g., bulletized return fields), but no sentence feels 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?

With no output schema, the description fully documents the return structure including integrationId, errorCount, warningCount, statusCounts, listingStatusCounts, dataCheckErrors, and channelErrors, plus nested error and fixSuggestions fields. It also covers edge cases like project_id optionality and the need to poll ad_status. An agent has everything necessary to invoke the tool and interpret its result.

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

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

Schema coverage is 0%, so the description must carry all parameter meaning. It explains that ad_id is 'the id from list_ads' and that project_id is 'OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).' This is exactly the kind of semantic routing information an agent needs, and it compensates fully 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?

Description opens with a specific verb-resource pair: 'Get the validation report for one ad' with the scope 'aggregated errors and warnings that block or degrade its feed, with fix suggestions.' It explicitly distinguishes ads from marketplaces ('Ads are ads-based channels... not marketplaces'), which separates it from get_marketplace_report. The report content and groups are also clearly stated, leaving no ambiguity about what the tool returns.

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 strong contextual guidance on when the report is meaningful: 'Data-check errors exist only after a generation has run — finish the wizard, or repair_ad to (re)generate; export is async, so poll ad_status until productsRefreshing AND productsSubmitting are false, then read the report.' It also clarifies ads vs marketplaces, which helps choose between get_ad_report and get_marketplace_report. It does not explicitly contrast with get_ad_item_report or get_ad_item_history, so it stops short of a full 5.

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

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

Beyond the readOnlyHint/destructiveHint annotations, it discloses pagination behavior (offset/nextOffset/hasMore), the critical value-vs-label semantics for the stored/exported value, and the empty-options edge case meaning the attribute is free-text. These are non-obvious behavioral details that an agent needs to invoke the tool correctly.

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 long but dense and logically ordered: core purpose, return shape, key semantics, application methods, pagination, and target selection. Every major sentence adds value, though some points could be tightened or bulleted to improve scannability without losing content.

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 tool with no output schema, the description fully covers what the tool returns, how to paginate, what empty results mean, how to choose the correct target, and where attribute_code originates. An agent has enough information to select and correctly invoke this tool without needing to inspect other schemas.

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 already covers 80% of parameters with descriptions, and the description adds important nuance beyond the schema: project_id is optional for single-project customers but required otherwise (call list_projects), and integration_id can be either a marketplace_id or ad_id. It also reinforces the 'exactly one of feed_id or integration_id' constraint. A strong supplement to already-good 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 states a precise verb-resource pair: it retrieves the allowed 'OPTION choices (value + label)' for a target feed/channel attribute, specifically for closed-option 'Set option' attributes. It clearly differentiates itself from related tools like map_feed_attribute, set_value, and discover_rule_operations by explaining its exact role in the workflow.

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 when-to-use and how-to-apply guidance: it names the two application paths (constant mapping via map_* tools vs. conditional rule with a 'setoption' operation), tells the user to use set_value when options are empty, and specifies how to choose between feed_id and integration_id. This leaves no ambiguity about how to route to 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 behavioral context beyond that: the rule set is SHARED per project + taxonomy_code + locale, which affects how results should be interpreted. It also discloses the optional/inferred nature of project_id. 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?

Six sentences, each adding unique value: core purpose, shared semantics, addressing modes, return shape, sibling routing, and optional parameter. Front-loaded with the purpose, no filler or repetition of schema content.

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 is no output schema, the description includes the return shape inline. It covers sharing semantics, addressing modes, sibling tools, and optional parameters. The only minor gap is the lack of explicit guidance on what happens when both feed_id and taxonomy_code are sent together, but this is an edge case for a read-only tool.

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

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

Schema description coverage is only 50% (taxonomy_code and taxonomy_locale are documented). The description compensates by explaining that feed_id selects the taxonomy via a feed, and that project_id is optional/inferred. It clarifies the relationship between parameters, though it doesn't state precedence if both feed_id and taxonomy_code are provided.

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 'Get the current category-mapping rules for a taxonomy' with an explicit mapping direction ('store categories → marketplace/taxonomy categories'), which is a specific verb and resource. It distinguishes itself from sibling tools like set_category_mapping by naming them in the description.

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

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

It explicitly states when to use alternatives: 'Use list_unmapped_categories to find gaps, search_target_categories to find a target, and set_category_mapping to fill them.' It also clarifies the two valid addressing modes (feed_id or taxonomy_code) and notes project_id is optional/inferred.

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 readOnlyHint=true and destructiveHint=false, and the description's behavior aligns with that. It adds substantial behavioral context beyond annotations: soft-deleted feeds return 'feed_deleted' rather than 'not_found', hidden attributes must never be mapped, ruleEnabled=false means a rule is attached-but-disabled and does not drive the value, and currencyConversionEnabled should be set false to avoid double conversion when the value is already in the target currency. This gives an agent real insight into subtle edge cases.

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 long, but it is dense with necessary edge-case information and every sentence earns its place. It is front-loaded with the core purpose and return shape before diving into semantic caveats. It could be better organized with bullets, but the single-paragraph structure is acceptable given the complexity.

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

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

With no output schema, the description must fully explain the return values and behavior, and it does so thoroughly: it enumerates the return fields, explains the attribute mapping semantics, notes editable settings, describes the soft-delete error path, identifies sibling tools for follow-up actions, and states prerequisites. Nothing critical appears missing for an agent to correctly invoke and interpret this 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 only 33%, so the description carries most of the parameter burden. It explains that feed_id comes from list_feeds/create_feed and that project_id is optional/inferred for single-project customers or required otherwise, with a pointer to list_projects. The response_format parameter is already well described in the schema with an enum and default, so the description doesn't need to repeat 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 opens with a specific verb and resource: 'Get the full detail of one feed: identity + state + the attribute mapping'. It then lists the exact shape of the return object, making the tool's responsibility unambiguous. It also differentiates itself from get_feed_status by explicitly scoping this tool to configuration/mapping rather than run 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 routing guidance: 'Use get_feed for configuration/mapping and get_feed_status for run progress.' It also explains when project_id is required and to call list_projects, and mentions the prerequisite that the project's data must be imported (dataStatus='ok', see get_import_status). These are concrete, actionable conditions for correct invocation.

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 reinforces this by stating it works on a read-only connection and does not regenerate. It additionally discloses the sensitive gate behavior, fileExists:false handling, and the distinction between metadata-only and row-returning responses, which goes well 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 long but every sentence earns its place by covering usage, parameters, return fields, and edge cases. It front-loads the core purpose and differentiation before diving into details, though it is slightly dense and could be broken into clearer sections. Still, for a tool this behavior-rich, the density is justified.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: every returned field is listed and key fields like feedUrl, productsCount, lastGeneratedAt, and sensitiveGate are semantically defined. The complete workflow from first call to gated sample to pagination is described, making the tool fully understandable 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?

Schema coverage is only 60%, but the description compensates fully: it explains feed_id provenance, project_id inference rules, sample_size default/max, offset paging semantics, and acknowledge_sensitive gating. This adds meaning beyond the raw schema, especially the non-obvious behavior of acknowledge_sensitive and the single-project inference for project_id.

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 ('Read') and resource ('CURRENT output of a feed's already-generated file') and immediately distinguishes itself from export_feed by noting it does NOT regenerate the file. An agent can clearly differentiate this tool from its closest sibling 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 explicitly tells when to use the tool ('see what a feed currently contains'), names the alternative export_feed and why it differs, and gives conditions for optional project_id. It also explains the sensitive-data workflow and pagination approach, leaving no ambiguity about how to proceed.

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=true and destructiveHint=false, and the description adds no contradiction. It enriches the read-only contract by enumerating the returned fields, the full status enum, and the expected next action per status, making clear that this is a safe, repeated polling operation.

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

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

Although long, the description is densely informative with no filler. The core purpose and return contract come first, followed by status semantics, action routing, and parameter provenance — each sentence earns its place given the lack of output schema and terse input 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?

With no output schema, no enum definitions, and 0% schema description coverage, the description carries the full burden and succeeds: it lists the return object, defines every status value, explains conditional parameter requirements, and gives status-specific follow-ups. Nothing essential for invoking this 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?

Schema description coverage is 0%, so the description must explain the parameters itself. It does: feed_id is defined as 'the id from list_feeds / create_feed', and project_id's optionality is clarified with the single-project vs multi-project inference behavior. This adds real meaning beyond the bare integer 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 opens with a specific verb and resource: 'Get the runtime status of one feed: generation state, progress, last run/submit and any error.' It also explicitly distinguishes itself from get_feed ('Use get_feed for configuration/mapping and this tool for run progress'), so an agent can choose among the large sibling set without guessing.

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 direct when-to-use guidance by naming get_feed as the alternative for configuration/mapping and this tool for run progress. It also explains the polling behavior ('processing/pending → keep polling'), error recovery ('error → read errorMessage, fix, export_feed'), and the conditional project_id requirement ('then call list_projects'), leaving little room for misuse.

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 adds substantial behavioral detail: status enums, polling semantics (running true while pending/processing), the meaning of dataStatus='ok' as the only state appropriate for mapping, and that recentRuns is newest-first. It also explains how to verify a specific import by type without contradicting 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?

Although lengthy, every sentence carries essential operational information: statuses, output fields, polling workflow, error handling, and project_id inference. The description is front-loaded with the core purpose and then systematically details the response shape and usage sequence, with 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 tool with one optional parameter and no output schema, the description is unusually complete. It documents the full response shape, all status values, execution semantics, related next-step tools, and a concrete polling procedure. Nothing an agent needs to invoke it correctly or interpret its results 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 0%, but the description fully compensates: it explains that project_id is optional, inferred for single-project customers, required otherwise, and instructs to call list_projects in the latter case. This adds meaning far beyond the bare integer schema definition.

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

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

States a specific verb and resource: 'Check whether a project's store data is connected, imported and fresh' before advising on feeds/mapping. This clearly distinguishes it from sibling tools like get_feed_status or list_feeds by establishing its role as a readiness/import verification step.

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

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

Provides explicit when-to-use guidance: before advising on feeds/mapping, after set_api_source/set_ai_source with apply:true, and when dataStatus is 'ok' then proceed to preview_products and list_feed_templates. It also explains the error path (read errorMessage, run_import to retry) and when to call list_projects, leaving no ambiguity about 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, so the safe read-only nature is covered. The description adds substantial behavioral context beyond these: it warns about the activation behavior that can spend budget, explains that secrets are never returned, notes taxonomyCode is read-only, and clarifies that the connection/auth step is not configurable. These are critical behavioral disclosures not captured by annotations. 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?

The description is very long, but every sentence carries essential information—it is dense, not verbose. However, it lacks any paragraph breaks or bullet points, making it a monolithic text wall. The purpose is front-loaded, but the rest could be better structured. Still, there is zero fluff, and the length is justified by the tool's complexity.

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 returns a highly nested structure with steps, fields, activation behavior, order sync, and connection details, the description covers everything an agent needs to invoke it and interpret results: it lists all return fields, explains step/field semantics, describes the auth step limitations, connection ownership, order sync conditions, and even mentions test_marketplace_connection. 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 0%, so the description carries full parameter documentation. It explains marketplace_id as 'the id from list_marketplaces / create_marketplace' and project_id as 'OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects).' This adds crucial meaning beyond the bare schema types.

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

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

The description opens with a specific verb and resource: 'Get the full detail of one marketplace: identity + state + the configuration wizard steps.' It clearly distinguishes itself from siblings by explicitly stating 'Use get_marketplace for configuration and marketplace_status for run progress,' and by contrasting with other getters like get_marketplace_channel and get_marketplace_attributes. The purpose is unmistakable and non-tautological.

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 when-to-use guidance: 'Use get_marketplace for configuration and marketplace_status for run progress.' It also explains when to call set_marketplace_product_mode (to set MANUAL mode before testing), when configure_marketplace_step applies, and when to call list_projects for project_id. It even states the auth step is not configurable via MCP and to never retry it. This is comprehensive routing advice.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses substantial behavior: the meaning of valueSource, the subtle ruleEnabled=false rule, currency conversion semantics, the provisional nature of results during warmup, and the 'configured/stepField/default' sourcing hierarchy. This is far more than the annotations provide.

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 information-rich, but it is long and contains some run-on sentences that require careful parsing. It is well front-loaded with the core purpose, but the sheer density and lengthy qualifiers reduce scannability slightly.

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 covers the return payload semantics, important edge cases, the warmup provisional state, and follow-up actions. There is no output schema, so the description carries the full burden and delivers nearly everything an agent needs to call it correctly and interpret results.

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 low (33%), but the description richly explains only_unresolved and project_id, and even clarifies the role of marketplace_id. It adds meaning beyond the schema by explaining what only_unresolved returns and when project_id is optional/required.

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 — listing a marketplace's OUTPUT attributes and their current sourcing — and immediately positions it as the tool for solving the attribute form, distinguishing it from generic get/list tools. It names related siblings (map_marketplace_attribute, configure_marketplace_step) without confusing its own role.

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 context for when to use this tool (when dealing with the attribute form), what to do after (map_marketplace_attribute), and how to handle caveats (categoryAttributeWarmup pending, polling marketplace_status, optional project_id). It also names the source of marketplace_id and when to call list_projects.

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 readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context: kind is always 'marketplace', versionType marks primary/default definitions, and capabilities describe supported features. It does not contradict annotations, and the added detail goes beyond what annotations alone convey.

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

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

The description is dense but every sentence contributes: purpose, return shape, key invariants, usage timing, and parameter sourcing. The inline return JSON is justified because there is no output schema, and the information is ordered logically from outcome to invocation.

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 there is no output schema, the description provides the full return structure and explains the key fields. It also covers the dependency on list_marketplace_channels and the project_id edge case, making the tool effectively callable without further research.

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

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

Schema coverage is only 50%, with channel_code documented in the schema but project_id not. The description compensates fully by explaining project_id's optional/required behavior and its source, and it reinforces that channel_code is the channelCode from list_marketplace_channels. This gives the agent sufficient parameter-level 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?

The description states a specific action and resource: getting, for ONE marketplace channel, the integration types and their capabilities. It clearly differentiates from list_marketplace_channels by emphasizing the singular channel focus and the capability details it returns.

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 call this before create_marketplace to choose the right definition, and clarifies that channel_code comes from list_marketplace_channels. It also explains when project_id is optional versus required, giving the agent concrete routing and prerequisite 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 description adds substantial behavioral detail beyond the readOnlyHint=true annotation: it discloses the response structure, newest-first ordering, that entries contain only process metadata not raw product values, and the distinction between raw event codes and human-readable labels. This is far more than the annotations alone convey.

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

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

The description is dense but every sentence contributes: purpose, return contract, field semantics, pairing recommendation, identifier provenance, and conditional parameter behavior. It is front-loaded with the core purpose and does not repeat the schema verbatim.

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 no output schema, the description embeds a full return contract including nested entry fields and the labels/raw-code distinction. It covers how to obtain parameters, when the tool is needed, and what the output means, making it fully actionable for an agent.

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 75%, so the schema already documents three of four parameters. The description adds meaningful extra semantics by clarifying that item_id is the same id used by get_marketplace_item_report, that marketplace_id is the integrationId from list_marketplaces, and that project_id is optional only for single-project customers. This goes beyond the bare 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 ('Get'), a precise resource ('ONE listing item's action-log timeline'), and the purpose (explaining WHY an item ended in its current state). It clearly differentiates from sibling tools like get_marketplace_item_report by focusing on the event timeline rather than current errors.

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?

Explicit guidance is given for when to use this tool: pair it with get_marketplace_item_report to diagnose a failing product. It also specifies where to obtain the required identifiers (item_id from list_marketplace_items, marketplace_id from list_marketplaces) and explains the optional project_id behavior, including when to call list_projects.

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

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

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses the sensitive-gate behavior — first call withholds currentValue, returns a sensitiveGate, and requires re-call with acknowledge_sensitive:true after user approval. It also explains the return payload semantics: raw codes vs human labels, error fields, source values, and level meanings. This is substantial behavioral context the annotations alone would not provide.

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 long but every sentence earns its place. It front-loads the core purpose, then packs return semantics, gate behavior, parameter sourcing, and the sibling distinction into a dense but scannable format. There is no filler or repetition of schema 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 no output schema, the description carries the full burden of explaining return values — and it does so thoroughly, covering status fields, error entries, enumeration values, the sensitiveGate flow, and parameter dependencies. Nothing needed to invoke 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?

Schema description coverage is only 25%, but the description compensates fully: it explains item_id and marketplace_id provenance, project_id optionality and inference, and the acknowledge_sensitive two-call flow. Every parameter's meaning and usage is clarified beyond the bare 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 opens with a specific verb/resource pair — 'Get the detailed report for ONE listing item of a marketplace' — and immediately states the tool's purpose. It also explicitly distinguishes itself from the sibling get_marketplace_report ('For the marketplace-wide breakdown'), so an agent can select it without 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?

The description gives clear when-to-use guidance: single item vs marketplace-wide, and names the alternative tool. It also tells the agent where the IDs come from (list_marketplace_items, list_marketplaces), explains when project_id is needed, and routes to list_projects when required. This is explicit, actionable selection 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the dependency on prior feed generation, the async export nature, the two error groups (dataCheckErrors pre-submission vs channelErrors post-submission), and the semantics of level/count/fixSuggestions. No contradictions with 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?

Dense but purposeful; the length is justified by the absence of an output schema and the nested return structure. It front-loads the core purpose, then methodically explains return shape, field semantics, prerequisites, and sibling routing. No wasted or redundant sentences.

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

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

For a tool with 2 parameters, no output schema, and nested return fields, the description covers everything needed: exact return JSON, field meanings, when data exists, how to poll, and how to act on fixSuggestions. An agent can invoke it correctly without guessing.

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%, but the description fully compensates: 'marketplace_id is the id from list_marketplaces' and 'project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects)' explains both parameters' origin, optionality, and conditional requirement.

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 object: 'Get the validation report for one marketplace: the aggregated errors and warnings that block or degrade its listing, with fix suggestions.' It explicitly differentiates itself from the sibling: 'for a single product's report use get_marketplace_item_report', making its marketplace-wide scope unmistakable.

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 direct routing to the alternative tool for single-product reports, and states when the report is meaningful: 'Data-check errors exist only after a generation has run — finish the wizard, or repair_marketplace to (re)generate; export is async, so poll marketplace_status until productsRefreshing AND productsSubmitting are false'. It also tells where to get marketplace_id and when to call list_projects for project_id.

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, but the description goes further by disclosing nuances like locked fields being paid features and options being potentially null until authentication. It also clarifies the relationship with configure_order_connection, adding significant value beyond structured metadata without any contradiction.

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 but every sentence carries weight: it states the purpose, lists the full output, explains key behaviors, and gives usage context. It is front-loaded with the primary function and structured logically, with no redundant or filler content.

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 is remarkably complete. It details the entire return payload, explains the meaning of locked and null options, indicates how to derive the required parameter, and instructs on the next step. With no output schema, the description fully carries the return-type burden.

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

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

The schema only documents connection_id, but the description compensates fully by explaining the source of connection_id and the conditional requirement for project_id. It adds meaning to both parameters that the schema lacks, especially for project_id which has no description in the schema.

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

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

The description clearly states it provides 'Full detail of ONE standalone order connection' with a specific verb and resource. It distinguishes itself from listing or overview tools by specifying it retrieves a single connection along with its configuration form. The output structure is explicitly enumerated, 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?

The description gives precise guidance on when to use this tool: it specifies that connection_id comes from get_order_overview, and explains the optionality of project_id with a conditional call to list_projects. It also directs the agent to use the returned orderConfigFields for constructing configure_order_connection calls, clearly placing this tool in the workflow.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the core safety profile is covered. The description adds useful context: the return fields, the orderStatus enum semantics, and that a new connection appears only after authentication. This exceeds the baseline without being redundant.

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 long but information-dense, with the core return fields listed up front and usage context following. Every sentence adds value, though the list of return fields could be considered verbose. It is well-structured and not padded.

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

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

With no output schema, the description carries the full burden of documenting the return shape and field semantics. It lists all expected fields, explains orderStatus values, notes sync-related fields, and covers project_id behavior. No critical information is missing for an agent to use 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?

The schema provides only a type and exclusiveMinimum for project_id, with no description (coverage 0%). The description fully compensates by explaining optionality, single-project inference, and the fallback to list_projects. This is critical information an agent needs to call the tool correctly.

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

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

The description uses a specific verb ('Returns') with a clear resource ('order counts and the project's order connections') and explicitly names the sibling tool (get_order_connection) it differs from. It distinguishes the overview from the drill-down without ambiguity.

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

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

It states 'Start here to see order state, then drill into one connection with get_order_connection,' giving explicit when-to-use and the alternative. It also explains the project_id optionality and when to call list_projects, covering edge cases for the parameter.

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 substantial behavioral context: the meaning of empty marketCategories lists, null handling for stats, field semantics (score confidence, source tags, freshness via metricsSyncedAt), and the optionality behavior of project_id. It fully discloses the tool's behavior beyond the safety hints.

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

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

The description is long but every sentence serves a purpose: the lead states the goal, then the output schema is detailed with field semantics, then usage instructions follow. No fluff or repetition. It is front-loaded with the core purpose and ends with actionable guidance. The length is justified by the complexity of the tool.

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

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

Given the rich output (no output schema provided), the description fully specifies the return structure, field meanings, null semantics, and how to use the data. It even references the prerequisite tool call for multi-project scenarios. An agent could confidently invoke and interpret the results without further documentation.

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

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

With one parameter (project_id) and 0% schema description coverage, the description compensates completely. It explains that project_id is optional for single-project customers and required otherwise, and directs to call list_projects when needed. This adds essential meaning that the bare schema (integer, exclusiveMinimum 0) does not provide.

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 clear, specific verb+resource: 'Get a project's catalog product profile so you can recommend suitable sales channels for it.' It states the primary purpose and the intended downstream use, distinguishing it from siblings like list_projects or get_marketplace. The tool's role in the channel-recommendation workflow is unambiguous.

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

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

Includes explicit guidance on when to use the tool and how to act on its output: cross-reference list_marketplace_channels / list_ad_channels, propose only channels with available=true, and never invent channels. Also clarifies the conditional need for project_id and when to call list_projects instead. No ambiguity remains.

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 annotation, the description reveals the exact return shape, the round-trippable nature of rules[], the 'not_found' error for unknown rule_id, and the conditional behavior for project_id. These are important runtime behaviors an agent cannot infer from annotations alone.

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 adds information: primary purpose, return contract, nested structure, scope semantics, error behavior, and parameter provenance. It is dense but structured, and the critical round-trip concept 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?

Given there is no output schema, the description provides the complete return shape and nested type details. It also covers error cases, parameter disambiguation, and relationships to sibling tools, leaving little ambiguity for an agent to invoke 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 coverage is only 33%, but the description compensates by explaining all three parameters: rule_id originates from list_rules, scope selects the library with a default, and project_id is optional in some cases but required in others, with a pointer to list_projects. This is exactly the semantic grounding the schema lacks.

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: 'Get the full definition of one product rule (Attribute Rule)'. It distinguishes itself from sibling tools like list_rules (full vs. summary), update_rule (round-trippable), and delete_rule by emphasizing the read-only retrieval and the exact return payload.

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 on how rule_id relates to list_rules, how the returned rule feeds update_rule, and when project_id must be supplied (by referencing list_projects). It does not explicitly spell out 'do not use this to list rules', but the phrase 'one product rule' and the round-trip workflow imply the boundary sufficiently.

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 declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by stating the tool 'runs no AI and never writes.' It additionally discloses the two-phase sensitive data gate, pagination via hasMore/nextOffset, and that unmapped values pass through unchanged—context well beyond what annotations provide.

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 long but every sentence carries operational weight: purpose, scope, alternative, return shape, parameter targeting, sensitive gate, and follow-up workflow. It is front-loaded with the core purpose and differentiation before diving into parameter details, 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?

Despite having no output schema, the description enumerates the full response shape including sourceValues, targetAllowedValues, alreadyMapped, hasMore, and nextOffset, and explains the sensitiveGate response. Given the tool's complexity—8 parameters, dual target types, and a sensitive-data gate—the description covers everything an agent needs 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?

With only 63% schema description coverage, the description compensates fully. It explains source_attribute_code as distinct store values, target_attribute_code as accepted target values, the exact semantics of feed_id vs integration_id, project_id inheritance, only_unmapped, acknowledge_sensitive, and offset/nextOffset pagination, plus the non-obvious array-of-objects format for search/replace.

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: 'Get the inputs needed to build a value-mapping rule' that remaps source values onto a target attribute's allowed set. It also distinguishes itself from the sibling get_attribute_options by contrasting value→value mapping with a single fixed 'Set option' assignment.

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 when-to-use guidance for value→value mapping and explicitly points to get_attribute_options as the alternative for a single fixed value. It also explains the follow-up workflow (add map_attribute_value via create_rule/update_rule, then attach via map_feed_attribute/map_marketplace_attribute/map_ad_attribute), leaving no ambiguity about the downstream steps.

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?

Read-only behavior is already declared by annotations, and the description reinforces it. It adds useful behavioral context: results vary by argument mode, a canonical help URL may be returned, and the tool is designed to keep context small by not preloading content. It does not mention behavior when both slug and query are provided, but that is a minor gap for this kind of lookup tool.

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

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

The description is dense but purposeful, with the core purpose and rationale front-loaded, followed by call patterns, use cases, and topics. It is somewhat run-on and could be split into clearer sentences or bullets, but every part contributes meaning without significant 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 read-only knowledge tool with two optional parameters and no output schema, the description covers invocation modes, return expectations, topic list, and when to use it. There is no output schema, so the description's mention of returned index/body/search results is enough for an agent to select and call it correctly.

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

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

Schema coverage is 0%, so the description must explain the parameters, and it does: slug returns one topic's full body with optional canonical URL; query performs a keyword search; no args returns the index. This substantially compensates for the bare schema, though exact slug rules and mutual exclusivity are not spelled out.

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 tool as an on-demand reference/knowledge fetcher, with explicit scope ('Koongo help/reference knowledge') and a specific set of topics. It distinguishes itself from the many item/status/report sibling tools by describing its role as the lookup aid for interpreting those tools' outputs.

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 defines three concrete call modes (no args for index, slug for topic body, query for search) and gives explicit when-to-use guidance tied to sibling tool families like list_*_items, get_*_item_report, *_status, and *_report. This leaves little doubt about when the agent should reach for this tool versus the surrounding operational 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=true and destructiveHint=false, and the description adds a wealth of behavioral context beyond that: paging semantics (hasMore + nextOffset), response shape, availability reasons (plan_limit vs appstore), and the invariant that orderSyncSupported is always false for ads. 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 long but information-dense; every sentence adds a distinct, useful fact. It is front-loaded with the core purpose, then flows into distinction, response format, field semantics, and workflow. No fluff or repetition of schema-only 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?

Given an absent output schema, the description fully compensates by enumerating the response fields and explaining key values (availabilityReason, authType, orderSyncSupported, etc.). It also covers edge cases like unavailable channels and project_id ambiguity, so an agent has everything 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 covers 75% of parameters, and the description meaningfully enriches the remaining 25% (project_id optional/inferred vs required, plus link to list_projects). It also explains how query, limit, and offset work together ('page with limit/offset', response carries hasMore + nextOffset) and describes returned fields that clarify what 'available' means.

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?

'Search the CATALOG of ADS channels you can ADD' states the exact verb, resource, and scope, and explicitly contrasts with list_ads ('to list the ads that ALREADY exist, use list_ads'). It also distinguishes ads channels from marketplaces, so an agent can separate it from list_marketplace_channels without opening the schema.

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

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

The description says when to use this tool versus list_ads, defines which channels qualify ('ads-based channels... not marketplaces'), and gives a concrete follow-on workflow: 'Use channelCode with get_ad_channel... then create_ad'. It also explains the project_id ambiguity and routes to list_projects when required, leaving no ambiguity about 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 only say readOnlyHint=true, openWorldHint=false, destructiveHint=false; the description adds essential behavior beyond that: some channels return an empty list, rows contain only identifiers and statuses (no gate), itemId is what subsequent report tools expect, and ad_id is the integrationId from list_ads. This is rich, accurate context.

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

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

The description is long, but it is dense and front-loaded with the core purpose, then the empty-list caveat, return shape, filtering/paging, and related tools. Every sentence carries useful information; the only minor issue is that it reads as a solid block without clear paragraph or bullet separation.

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

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

With no output schema, the description compensates by explicitly listing the return shape, explaining the empty-list case, covering filtering and pagination, clarifying what data rows do and do not contain, and pointing to related tools for deeper item data. For an 8-parameter list tool in a sibling-heavy context, this is 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 already strong at 88%, with descriptions on most parameters. The description adds value by grouping filter parameters by purpose, explaining the relationship between ad_id and list_ads, and clarifying that project_id is optional for single-project customers but required otherwise — information the schema does not convey.

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

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

States a specific verb and resource: 'List the individual listing items of one ADS integration — the per-product rows'. It clearly distinguishes this tool from bulk channels and related tools like get_ad_report, and explains what kind of channel produces these rows.

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 says when not to use it (Google Shopping style bulk channels) and names the alternatives (ad_status / get_ad_report). It also gives practical usage guidance: filter with koongo_status, channel_status, listing_id or product_id to find failures, page with limit/offset, and use get_ad_item_report for full error reports.

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 read-only and non-destructive behavior, and the description adds valuable context: return shape, row fields, absence of order sync, and the meaning of project_id omission. It clarifies what the tool does and returns, going well beyond the structured 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 but every sentence adds essential information: tool scope, sibling differentiation, return structure, parameter semantics, and integrationId linkage. Information is front-loaded with the core action and definition first.

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

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

With no output schema, the description provides the full return structure and key field list. It covers the optional parameter behavior, error signaling, and how the returned integrationId connects to other tools. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 0%, but the description fully compensates by explaining the project_id parameter: optional, scopes to one project or all projects, and its relationship to project_id_required. This gives the agent complete semantic understanding beyond the bare integer type.

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

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

The description clearly states the tool lists existing ads for a project, distinguishing it from list_ad_channels and clarifying that ads are ad-based channels, not marketplaces. It explicitly differentiates from siblings and gives the exact resource being operated 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?

It explicitly says when to use list_ad_channels instead, explains the optional project_id behavior with and without it, and describes what to do if project_id_required is returned. This is direct, actionable routing guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description documents the exact return shape {items:[{code, url, handle}]} and explains the meaning of each field, including the custom_<code> behavior and join semantics of handle. It also discloses that project_id may be inferred, adding valuable runtime behavior not present in 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 compact and front-loaded with the core action. Every sentence adds necessary information: the purpose, the response contract with field semantics, and the only parameter's optionality. There is no wasted text.

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

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

For a simple list operation with one optional parameter and no output schema, the description is complete. It gives the return format, explains what code and handle mean, and clarifies project_id behavior, so an agent has everything 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?

The input schema provides only the integer type and exclusiveMinimum for project_id, with 0% schema description coverage. The description compensates fully by stating that project_id is optional and inferred for single-project customers, which is essential 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 clearly states a specific verb and resource: 'List the AI sources currently registered on a project'. It ties the data to set_ai_source, which helps distinguish from set/delete_ai_source, but it does not explicitly contrast with list_api_sources, leaving some sibling differentiation to the tool names.

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 see AI sources that were previously populated via set_ai_source. It also clarifies that project_id is optional and inferred for single-project customers. However, it does not explicitly state when to prefer this over related list tools such as list_api_sources or list_source_attributes.

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, idempotent, and non-destructive. The description adds useful behavioral detail beyond that: it states the exact return shape '{codes:[...]}' and discloses that project_id is inferred for single-project customers. No contradictions exist between description and 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 two succinct sentences with no filler. It front-loads the core purpose, then quickly covers output shape and parameter behavior, earning every word.

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 list operation with one optional parameter and no output schema, the description is complete. It covers what is listed, where the data comes from, how it is used, what is returned, and when project_id can be omitted.

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%, but the description compensates fully for the single parameter by explaining project_id is optional and inferred for a single-project customer. This gives the agent the key semantic nuance that the bare integer schema does not provide.

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 and resource: it lists 'API source attribute codes registered on a project' and clarifies their role as 'usable in rules as api_source.<code>'. This clearly distinguishes it from generic list tools and connects it to set_api_source.

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 context for when to use the tool: to retrieve API source codes, especially after set_api_source. It also explains project_id optionality and inference for single-project customers, but it does not explicitly contrast this with sibling tools like list_source_attributes or list_ai_sources.

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 readOnly and non-destructive annotations, the description discloses the exact return fields, the exclusion of integration-managed feeds, the error sentinel project_id_required, and the non-paginated complete-return behavior. This gives the agent a full behavioral model of the operation beyond what annotations alone provide.

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 adds a distinct fact: the sibling distinction, item shape, parameter semantics, error recovery, feedId usage, standalone-only exclusion, and pagination behavior. Despite being longer than typical descriptions, there is no filler and the most important scoping detail 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 one-optional-parameter read-only list tool, the description covers the return schema, error handling, exclusions, and pagination, so an agent can select and call it correctly without needing additional lookups. There is no output schema, but the inline item field list fully compensates.

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 only 'optional integer project_id' with zero description coverage, so the description carries the full burden and succeeds. It explains the semantic difference between passing and omitting project_id, the error condition that triggers its use, and the fact that each result carries its projectId even in the cross-project case.

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 precise verb and resource: it lists the customer's already-created feeds, explicitly distinguishing these from the catalog of feed types by naming list_feed_templates as the alternative. It even enumerates the returned item shape, removing ambiguity about what a 'feed' is in this 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 explicitly says to use list_feed_templates for the catalog, and explains the optional project_id behavior with clear conditions: with it you get that project's feeds, without it you get all projects' feeds. It also handles the project_id_required error by directing the agent to list_projects to pick a project, and maps feedId to feed_id for get_feed/verify_feed_attributes.

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 read-only and non-destructive, and the description adds behavioral details: the project_id_required error/inference behavior, that all matches are returned unpaginated, and the item field structure. It clearly states the scope ('PUBLIC templates') and 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?

Although longer than average, every sentence adds actionable information: differentiation, item structure, parameter guidance, and workflow. The text is front-loaded with the core definition and structured logically from purpose to usage to parameters.

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

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

With no output schema, the description tells the agent exactly what items look like ({feedCode, name, type, fileType, channelCode, country}), how to handle both parameters, and what to do with results. No critical invocation details are 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 has 0% description coverage, so the description carries the full burden. It fully defines query semantics (broad coarse filter, channel name, what to exclude) and project_id semantics (optional, inferred for single project, required and obtained via list_projects otherwise).

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?

Opens with a specific verb and resource: 'List the PUBLIC Koongo feed TEMPLATES available for a project'. It states the purpose as 'the catalog of feed TYPES you can create from' and explicitly differentiates from list_feeds, so an agent can distinguish 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?

States when to use list_feeds instead for existing feeds, and when to call list_projects and pass a project_id if project_id_required. Gives precise query strategy: use coarse channel names like 'google', avoid country/format/language words, and match structured fields manually. Also routes the resulting workflow to create_feed after user confirmation.

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 readOnly/destructive annotations, the description explains pagination semantics (hasMore, nextOffset), availability=false reasons (plan_limit, appstore, fallback) with the relevant remedy URLs, authType values, and project_id inference. This is substantial behavioral context an agent cannot derive from annotations alone.

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 but every sentence earns its place: disambiguation, search/pagination behavior, response shape, availability semantics, and downstream tool chaining. It front-loads the key distinction from list_marketplaces and stays organized despite the 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?

With no output schema, the description fully documents the response envelope and channel fields, pagination behavior, availability reason variations, and project_id handling. It also names the follow-up tools needed to complete the workflow, making the definition complete 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 documents limit, query, and offset, but the description adds real meaning: query matches channelCode/label with an 'amazon' example, limit/offset produce hasMore/nextOffset, and the undocumented project_id parameter is fully explained as optional/inferred or requiring list_projects. This goes well beyond the schema.

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

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

The description states a specific verb and resource: searching the catalog of marketplace channels that CAN be added, listing concrete examples (Amazon, eBay, Kaufland). It explicitly contrasts with list_marketplaces, which lists already-existing marketplaces, fully differentiating it from the closest 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?

It gives explicit routing: use list_marketplaces for existing marketplaces, use channelCode with get_marketplace_channel then create_marketplace, and call list_projects when project_id_required. These when/alternative instructions leave no ambiguity about how to use this tool in context.

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

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

Annotations already mark the tool readOnly and non-destructive, but the description adds meaningful behavioral context: it explicitly states that no user confirmation is required because no raw attribute values are exposed, clarifies the distinct meanings of status versus channelStatus, and explains that itemId is the value to pass to get_marketplace_item_report. No contradictions with annotations exist.

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 but organized: it front-loads the core purpose, then gives the exact return shape, then parameter semantics, filters, pagination, and cross-tool usage. Every clause adds information needed to invoke the tool correctly, and there is no filler or repetition of the tool name.

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

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

With 8 parameters, no output schema, and no enums, the description carries a heavy burden, and it fully meets it. It specifies the complete return structure, the semantics of status fields, the behavior around confirmation, filtering, pagination, the source of marketplace_id, and the project_id edge case. An agent has everything needed to call this tool correctly and to decide whether a different tool is 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?

Although the schema already documents most parameters, the description adds significant meaning: marketplace_id is identified as 'the id from list_marketplaces', project_id is explained as optional and inferred for single-project customers, koongo_status is illustrated with 'e.g. the failed items', and the mapping from return fields to downstream tool parameters is made explicit. This materially exceeds the schema's 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 opens with a specific verb and resource: 'List the individual listing items of one marketplace — the per-product rows of what is (or should be) listed on the channel.' It clearly scopes the tool to a single marketplace and distinguishes it from the closely related get_marketplace_item_report, so an agent can tell exactly what this tool returns.

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 routing guidance: it says list_marketplace_items needs no confirmation because it never returns attribute values, while get_marketplace_item_report should be used when actual values or full error reports are needed. It also explains how to use filters to 'drive a fix', how pagination works with limit/offset, and when project_id is required versus optional.

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 no safety contradiction exists. The description adds substantial behavioral context: it clarifies these are created/existing integrations, explains the optional project_id behavior, lists the exact response fields and wrapper, and tells the agent that integrationId maps to marketplace_id in other tools. This goes well beyond what annotations provide.

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 but every sentence earns its place. The core distinction from list_marketplace_channels is front-loaded, and the subsequent sentences cover return shape, parameter behavior, error handling, and cross-tool ID mapping. Given that there is no output schema, the field enumeration is justified rather than 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 simple read-only list tool with one optional parameter and no output schema, the description is complete. It covers the purpose, the sibling distinction, parameter semantics, error behavior, response structure, and how results relate to other tools. Nothing an agent needs to call 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 description coverage is 0%, so the description carries the full explanatory burden for the single parameter. It thoroughly defines project_id semantics: optional, what happens when provided vs omitted, and how to recover from the project_id_required error. This adds meaning far beyond the bare integer type in the schema.

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

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

The description states a specific verb and resource: list the already-created marketplace integrations of a project. It explicitly distinguishes itself from list_marketplace_channels, which is the catalog of channels that can be added, so there is no ambiguity about scope. The phrasing is specific and not a tautology.

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 guidance: pass project_id to get a specific project's marketplaces, omit it to get all projects' marketplaces. It also names the alternative tool (list_marketplace_channels) and tells the agent when to use that instead. It even handles an error condition (project_id_required) with a concrete remedy.

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, and the description adds meaningful behavioral context: the 'available' flag reflects the plan's order-connection limit, authType values are disclosed, and the project_id inference behavior is explained. These details go well beyond the structured 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 but every sentence carries decision-relevant information: purpose, distinction from alternatives, return shape, field semantics, next-step action, and parameter nuances. Nothing is 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?

Without an output schema, the description fully specifies the return shape and field semantics. It also covers filtering, optionality, edge-case behavior, and the follow-up call to create_order_connection, making it complete for correct tool selection and 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?

The query parameter is already documented in the schema, and the description reinforces it. The project_id parameter, which lacks schema documentation, is meaningfully clarified with optionality rules and the list_projects fallback, compensating for the partial 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 names a specific verb and resource ('List the marketplaces that can be added as a standalone ORDER connection') and immediately distinguishes them from wizard-based channels. It is clearly differentiated from sibling tools like list_marketplaces and create_marketplace.

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 this tool versus create_marketplace, and gives the decision rule based on whether a channel has a product wizard. It also explains the project_id edge case and routes to list_projects when required, leaving no ambiguity about invocation conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it guarantees no PII is ever returned, explains why the error reason is intentionally hidden (to avoid leaking customer data), and notes the conditional requirement for project_id based on the project's configuration. All this is beyond what annotations provide.

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 but every sentence earns its place. It is front-loaded with the core purpose and PII-free guarantee, then systematically covers use case, parameters, return structure, and a conditional routing note, 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 read-only list tool with four optional parameters and no output schema, the description fully equips the agent: it explains the response shape ({orders:[...], total}), the meaning of syncStatus, the deliberate absence of error reasons, and the conditional project_id behavior. Nothing essential is missing for correct invocation.

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

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

Schema covers 75% of parameters (limit, errors_only, connection_id), but the description adds meaning for all four: it specifies the default and max for limit, the filtering intent of errors_only, the restriction and source for connection_id (from get_order_overview), and clarifies project_id's optionality with a route to list_projects. This significantly compensates for the missing project_id 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 states a specific verb ('List') and resource ('recent order records') and immediately clarifies the PII-free nature, which distinguishes it from sibling tools. It explicitly routes to list_projects when project_id is required, making differentiation 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?

It provides a clear primary use case ('Best for spotting sync problems') and explains how to filter with errors_only. It also gives an explicit exception: 'project_id is OPTIONAL (project_id_required otherwise — then call list_projects)', which guides the agent to the correct alternative.

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

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

Beyond the readOnly/destructive annotations, it discloses important hidden behavior: an empty list does not mean no projects, broad searches may be capped, and REVOKED/OVERLIMIT projects are still listed. It also explains apiStatus semantics, adding real operational context.

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

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

The description is long but every sentence earns its place: core purpose and return shape up front, then usage guidance, edge cases, and next steps. There is no filler or redundant repetition 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?

With no output schema, the description still provides the item structure, status meanings, empty-list caveat, and a suggested next step. An agent has enough context to invoke it correctly and handle unusual responses.

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?

Although the schema covers 100% of the single `query` parameter, the description adds substantial value by naming what can be searched (name, code, owner email), warning that broad searches may be capped, and advising specific queries. This is more than a restatement of the schema.

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

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

The description states exactly what the tool does ('List your projects'), enumerates the item shape, and frames it as the first discovery step when a projectId is unknown. It clearly distinguishes this tool from the many other project-requiring 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?

It gives explicit when-to-use guidance ('Call this FIRST when you don't know which project to act on'), when not to use it ('When you own a single project you usually don't need this'), search behavior, empty-list retry instructions, and the recommended follow-up tool. This is unusually complete.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses substantive behavior: the exact return shape, that returned === total with no pagination, the meaning of usageCount, and the semantics of scope and query as a substring on NAME only. No contradiction with annotations 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?

The description is dense and front-loads the core purpose and return shape. A few phrasings repeat the schema (e.g., scope enum, query substring), but they are integrated with extra context rather than pure duplication, and no sentence is gratuitous.

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

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

With no output schema, the description carries the burden of explaining return values, which it does: {rules:[...], returned, total}, plus pagination behavior and usageCount semantics. It also points to get_rule for full details, making the tool's scope complete for an agent deciding to 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?

The schema covers query and scope, but project_id has no schema description; the description fills that gap by explaining it is optional, how it is inferred for single-project customers, and when list_projects must be called. It also adds operational nuance to query (coarse pre-filter, non-unique names, disambiguation duty) that goes beyond the schema text.

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

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

The description opens with a specific verb and resource: 'List the product rules (Attribute Rules) available to a project.' It explicitly distinguishes itself from get_rule ('Use get_rule to fetch a rule's full rules[]') and from the broader rule lifecycle tools, so an agent can confidently separate list from create/update/delete/get 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?

The description gives explicit conditional guidance: scope selects which library, query is a coarse pre-filter, and project_id is optional for single-project customers but required otherwise, with the instruction to call list_projects in that case. It even warns about non-unique rule names and advises the agent to confirm matches — clear when-to-use and when-not-to-use direction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is fully consistent with them. Beyond the annotations, the description discloses the exact return shape ({attributes:[{code, label, dataType}], returned, total}), the non-paginated single-call behavior (returned === total), the conditional taxonomy behavior depending on which id is passed, and the data-import prerequisite — all genuinely additive context.

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

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

Seven sentences, each earning its place: purpose with examples, return shape, parameter differentiation, call ordering, optionality logic, prerequisite, and pagination. The most decision-critical fact (relationship to map_feed_attribute) is front-loaded in the first sentence, and there is no redundancy or 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?

Given the tool's complexity — conditional parameter behavior, a prerequisite dependency, a downstream caller relationship, no output schema, and 0% schema coverage — the description is remarkably complete. It covers return format, non-pagination, the neither-parameter case via the inference logic, and points to both get_import_status and list_projects for adjacent concerns. 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 description coverage is 0%, so the description carries the full burden — and it delivers. It explains that feed_id adds the feed's taxonomy_* attributes for editor parity, that project_id alone omits taxonomy, and that project_id is optional but conditionally required (inferred for single-project customers, otherwise call list_projects). This semantic distinction between the two integer parameters is exactly what an agent needs to choose correctly.

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

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

The description opens with a specific verb and resource ('List the source attributes the store provides') and immediately defines the tool's purpose: it enumerates the valid platform_code values for map_feed_attribute. Concrete examples (brand, ean, price, color, category_name) anchor the meaning, and the explicit link to map_feed_attribute distinguishes it from sibling attribute tools like get_ad_attributes or get_marketplace_attributes.

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

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

Usage guidance is explicit and actionable: 'Call this BEFORE map_feed_attribute to choose a valid platform_code' states the ordering constraint directly. It also covers when to pass each parameter (feed_id for full parity with taxonomy_* attributes vs project_id alone), when project_id is inferred vs required, routes to list_projects as an alternative, and names the prerequisite get_import_status.

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, and the description adds further behavioral detail beyond that: it documents the exact return shape, pagination semantics via hasMore/nextOffset, the paging loop until hasMore is false, and the project_id inference rule. No annotation 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?

The description is dense but each sentence contributes: scope, return shape, downstream usage, project_id nuance, and pagination. Some limit/max information is repeated from the schema descriptions, but the repetition is minor and the text remains front-loaded and 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 output schema provided, the description fully covers the return object structure and the pagination protocol, which is essential for an agent to call this tool correctly. The optional parameter handling and downstream consumer tools are also explained, leaving no significant gap for 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?

limit and offset are already well documented in the schema, while project_id has no schema description; the description compensates by explaining when it is optional, inferred, or required and how to resolve it via list_projects. This adds meaning beyond the schema for the one under-documented parameter.

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