mcp-server

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

Annotations already mark this as a safe idempotent read, but the description goes well beyond: it explains isOverlimit/upgradeUrl=null semantics, the meaning of productsRefreshing/productsSubmitting as a WAIT signal, that productStats and dataCheckErrors are stale mid-refresh, and the categoryAttributeWarmup states (pending/rescheduled/failed) with retry behavior. This is unusually rich behavioral disclosure.

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

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

The core purpose and sibling routing are front-loaded, but the body is long and rambling with a broken sentence mid-way that merges an ad_id explanation with the warmup discussion. Dense and mostly useful, yet it repeats the wait/poll idea and could be tightened.

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 enumerates every returned field and its interpretation, covers the polling lifecycle including rate-limit and terminal states, and clarifies the ad_id/project_id inputs. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 0%, so the description must compensate. It clearly explains project_id as OPTIONAL (inferred for single-project customers, else project_id_required → call list_projects), which is real added meaning. The ad_id sentence is garbled ("ad_id is the id from categoryAttributeWarmup is the OTHER wait"), leaving ad_id's source only loosely implied via the list_ads reference.

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 ("Get the live run status of one ad") and enumerates the facets returned (readiness, connection, product counts). It explicitly distinguishes itself from siblings: "Use ad_status for run progress and get_ad for configuration/mapping. For the detailed error breakdown use get_ad_report." An agent can route without opening the schema.

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

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

Gives explicit when-to-use and when-to-wait rules: poll until BOTH productsRefreshing and productsSubmitting are false before reading results. It names alternatives by condition (get_ad for config, get_ad_report for errors, refresh_ad_category_attributes on 'failed') and explains the ad_id provenance and project_id fallback path.

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 a non-read-only, non-idempotent, non-destructive write. The description adds value beyond that by disclosing the exact return shape and semantics (integrationId is the id of the NEW clone, not the source). It doesn't explicitly discuss repeat-invocation behavior, but the copy-creation framing is clear and consistent 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?

Front-loads the core action, then layers domain context, return shape, and parameter meaning. Every sentence earns its place, though the density is high and could be broken up slightly for scanability.

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

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

For a 2-parameter clone tool with no output schema, the description supplies the return structure, the meaning of the returned id, and the source of both parameters. 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 must carry the load — and it does. ad_id is defined as the source ad from list_ads, and project_id is explained as optional with the inference rule and the fallback action (list_projects) when it becomes 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?

Starts with a specific verb+resource ('Clone an ad — create a copy of it (settings and configuration) as a new ad') that is unambiguous. It further disambiguates the resource by defining what 'ads' are versus marketplaces, so the agent can distinguish it from clone_marketplace without opening the schema.

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

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

Gives clear context and prerequisites: ad_id comes from list_ads, and project_id is optional for single-project customers but otherwise requires calling list_projects. It also clarifies the ads-vs-marketplace domain so the wrong sibling isn't chosen. It stops short of an explicit when-not-to-use / alternative statement (e.g., vs create_ad), so 4 rather than 5.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description goes beyond them by disclosing the return payload shape and stressing that integrationId refers to the NEW clone, a genuinely useful non-obvious detail. It stops short of stating permission requirements or whether the clone is reversible.

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

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

Front-loaded with the core action, then the return values, then parameter sourcing. Dense and all content earns its place, though the single long sentence mixing return shape and parameter semantics is slightly awkward to scan.

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 compensates by enumerating the returned fields and clarifying the id semantics. Combined with the annotations covering safety traits and the description covering both parameters, an agent has everything needed to call this clone operation 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 0% schema description coverage, the description carries the full burden and does so: marketplace_id is defined as the source from list_marketplaces, and project_id is explained as optional with the inference rule and the project_id_required fallback. Both parameters gain meaning not present 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?

States a specific verb (clone) and resource (marketplace), and immediately clarifies the semantics: it copies existing settings and configuration into a new marketplace, distinguishing it from create_marketplace. An agent can pick it apart from the many create_/configure_ siblings without opening a schema.

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

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

Gives operational routing: marketplace_id comes from list_marketplaces, and project_id is optional with an explicit fallback condition (call list_projects when project_id_required). It does not state when to prefer this over create_marketplace or clone_ad, but the conditional guidance is clear and actionable.

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

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

Annotations declare destructiveHint=true, idempotentHint=false, openWorldHint=true, but the description adds far more: the SUMMARY step finishes and ACTIVATES the ad, publishing every matching product to a live channel and spending budget; terminal 'oauth_required'/'credentials_in_ui' states with a stop-and-wait protocol; out-of-order calls returning prerequisite_not_met; async export/generation and category-attribute warmup requiring ad_status polling; and the full status enum. This is exactly the behavioral context annotations cannot carry.

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

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

Very long, but dense and front-loaded with the highest-risk fact (activation/spend) before the mechanical ordering rules. Almost every sentence carries operational weight; only the step_type/step_index redundancy with the schema description is mildly duplicative.

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 complex, stateful, destructive 5-param tool with no output schema, the description covers ordering, error statuses, terminal handoff, async side effects, the return object shape, and a pointer to the full walkthrough knowledge slug. Nothing an agent needs to invoke it safely 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 60%, and the description compensates well: it explains step_index vs step_type disambiguation (type alone targets the first matching step), that connection/auth steps take no payload, that dropdowns take options[].value not list position, and that project_id is optional/inferred or project_id_required. Some of this (step_type ambiguity) is already in the schema's own description, slightly reducing the added value.

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

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

Opens with a specific verb+resource and scope ('Configure ONE step of an ad's setup wizard'), and the capitalized 'ONE' plus the step-by-step guidance clearly differentiates it from configure_marketplace_step and configure_order_connection. An agent can identify this as the ad-wizard step configurator 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?

Explicit about when to use it (repeatedly, in order, targeting nextStepType until null), when NOT to (connection/auth step is never configurable here; must hand off oauthUrl and STOP), what to do first for safe testing (set_ad_product_mode to MANUAL, run_ad_item_action, check activationBehavior), and which siblings to consult (set_ad_product_mode, koongo_knowledge, get_ad, list_projects). Alternatives and exclusions are both present.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds crucial behavior beyond them: the SUMMARY step activates the marketplace and in AUTO mode publishes every matching product to the LIVE channel (spending budget), oauth_required/credentials_in_ui are terminal hand-off-to-user states, and export/category-attribute work runs async requiring polling. This is rich, non-redundant behavioral disclosure.

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

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

Front-loaded with the CRITICAL activation warning, and nearly every sentence carries operational weight. It is dense and lengthy — the wall-of-text format slightly hurts scanability — but few sentences are truly expendable.

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

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

For a destructive, non-idempotent mutation tool with no output schema, the description covers return shape (explicit fields and status enum values), async polling, error cases, and hand-off states. Nothing an agent needs to call this 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 60%, and the description compensates meaningfully: payload derives from get_marketplace steps[].fields, connection steps take no payload, step_type targets the first step of that type while step_index disambiguates, and marketplace_id/project_id origins and inference rules are spelled out. It adds real meaning beyond the schema, though some param detail (fieldCode formats) is deferred to koongo_knowledge.

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 ('configure'), resource ('one step of a marketplace's setup wizard') and scope ('ONE step'), making it immediately distinguishable from siblings like configure_ad_step and configure_order_connection. An agent knows exactly what this does without opening the schema.

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

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

Explicitly defines the in-order workflow (call repeatedly targeting nextStepType until null), the step_index vs step_type selection rule, the out-of-order failure modes, and the terminal oauth/credentials branch. It also routes to alternatives and prerequisites: set_marketplace_product_mode, run_marketplace_item_action, get_marketplace, marketplace_status, and koongo_knowledge for the full walkthrough.

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 cover the safety profile (idempotent, non-destructive), and the description goes well beyond them: it discloses merge semantics ('other settings are left untouched'), the exact 'updated'/'rejected'/'prerequisite_not_met' outcomes with HTTP codes, that a rejection saves NOTHING, the 409 auth prerequisite, and the metered-charge refusal on reactivation. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the core action, then dense multi-clause sentences covering errors and prerequisites. It is wordy at the margin but nearly every clause carries operational signal, so little 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 mutation tool with no output schema, the description supplies the return shape, all failure modes, prerequisites, and merge behavior, leaving nothing an agent needs to call it correctly unspecified.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds genuine value: it points order_config codes at get_order_connection.orderConfigFields, states connection_id comes from get_order_overview, and clarifies project_id's optionality and the project_id_required fallback.

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

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

States a specific verb ('Set') and resource ('standalone order connection's Orders Config, sync level and on/off state') with precise scope. The closing line 'Only order settings are changed here — marketplace credentials are NEVER set via MCP' cleanly separates it from the marketplace configuration 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?

Gives real routing guidance: complete authentication in the Koongo UI and confirm with test_order_connection before enabling, and use list_projects when project_id_required. It stops short of naming which sibling tool to use instead for adjacent configuration tasks, so it is clear but not exhaustively comparative.

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 it is a non-idempotent, non-destructive write. The description goes well beyond: it explains the full response envelope, the two possible status values including the HTTP 409 prerequisite failure mode and plan-limit entitlement errors, and that the returned integrationId serves as the ad_id for downstream tools. This is rich behavioral context that annotations cannot carry.

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

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

Dense but front-loaded: the core action and domain distinction come first, then parameter semantics, then the return contract. Every sentence earns its place, though the single-paragraph form is heavy for quick scanning.

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 shape (integrationId, action, status, kind, editUrl, nextStepType, message) and the create→configure workflow, covering everything an agent needs to call correctly and act on the 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 80%, but the description adds meaning beyond it: channel_code provenance, definition_code = specific-vs-default behavior sourced from get_ad_channel definitions[].definitionCode, multichannel_code linking semantics, name being optional and non-unique (changeable via set_ad_name), and project_id inference/fallback via list_projects.

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

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

States a specific verb+resource ('Create a new ad for a project') and explicitly distinguishes the ads domain from marketplaces ('Ads are ads-based channels... not marketplaces: they publish products to the ad platform and have no order sync'). This differentiation from siblings like create_marketplace is unusually precise.

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 chains the workflow: channel_code from list_ad_channels, then continue with configure_ad_step starting at nextStepType, and definition_code comes from get_ad_channel. It also states when-not conditions (status 'prerequisite_not_met' explains what must be done first).

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

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

Annotations declare this is a write (readOnlyHint=false, destructiveHint=false, non-idempotent), and the description adds substantial context: the quota_reached HTTP 403 refusal with addonCode, the instruction not to retry or offer an upgrade, the returned field set including categoryMappingNeeded, and the dataStatus prerequisite. This goes well beyond what 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?

Front-loads the core action and returns, then sequences workflow guidance in a dense but readable block. It is longer than typical, but nearly every clause adds actionable information; minor tightening could remove some repetition around category vs attribute mapping.

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 0% parameter coverage, the description supplies the return shape, prerequisites, error behavior, and the full downstream mapping sequence. An agent can complete the create-and-map workflow without opening sibling 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?

Schema description coverage is 0%, so the description carries full responsibility. It documents feed_code semantics (must come from list_feed_templates) and project_id optionality including the exact inference rule and error path when several projects exist — meaning well beyond the bare integer/string schema.

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

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

States a specific verb+resource ('Create a Koongo product feed for a project') and immediately distinguishes itself from related tools by mandating feed_code from list_feed_templates. The follow-on workflow description makes its role in the feed lifecycle unambiguous relative to siblings like update_feed, delete_feed, and map_feed_attribute.

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 to omit project_id (single project vs several), names the fallback tool (list_projects) and error (project_id_required), and lays out the required prerequisite (data imported, see get_import_status). It also names the exact downstream tools (get_feed, list_source_attributes, map_feed_attribute) and clarifies that category mapping does not cover attributes, giving an agent precise routing.

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

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

Annotations only give the safety profile (non-read-only, non-idempotent, non-destructive). The description goes well beyond that: it documents the returned object shape, both status values ('created' vs 'prerequisite_not_met' with HTTP 409), and the concrete prerequisite failure causes (missing offer/primary feed, plan limit, missing primary channel). No output schema exists, so this return-value disclosure carries real weight.

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 content is valuable but delivered as one dense paragraph with nested parentheticals and some near-verbatim overlap with the schema descriptions (channel_code, definition_code). It is front-loaded on purpose, but readability suffers and a few clauses could be trimmed or split into a structured block.

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

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

For a mutation tool with no output schema and 7 parameters, the definition supplies the parameters' origins, success/failure semantics, follow-up tool, and the returned fields. Nothing an agent needs to invoke it correctly or handle the response appears to be 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 already 86%, yet the description adds non-schema meaning: that definition_code should be omitted to get the default, the explicit primary_sync-vs-versionType disambiguation, that names are non-unique and mutable via set_marketplace_name, and that project_id is inferred for single-project customers. This is genuine added semantics rather than restatement.

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

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

States a specific verb+resource ('Create a new marketplace integration for a project') and immediately ties the required input to its source tool (list_marketplace_channels). An agent can distinguish this from sibling creators like create_ad, create_feed, or clone_marketplace without opening any schema.

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

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

Explicitly names the alternative/informational tools (list_marketplace_channels for channel_code, get_marketplace_channel for definitions, list_projects on project_id_required) and prescribes the next step via configure_marketplace_step on success. It also enumerates the failure branches and what to do about them, leaving little to inference.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, so safety is covered; the description adds substantive behavior on top: return statuses, the billing-eligibility gate, the 'rejected' branch with no activation link, and the fact that the user completes auth in the browser. It does not cover pagination or link expiry, keeping it short of a 5.

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

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

Front-loaded with the core action and its exclusions, then the outcome branches and follow-ups. Dense and well-ordered, though the billing/upsell instruction runs a little long for a single-sentence constraint.

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, and the description supplies the return semantics (auth_required + authUrl vs rejected) that the schema would otherwise carry. Combined with prerequisites, follow-ups, and the optional-parameter note, an agent has everything needed to call and sequence 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 50%, and the description compensates for the undocumented project_id by explaining it is optional for a single-project account, while channel_api_code is already documented in the schema. This adds real meaning beyond the structured fields for the gap parameter.

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

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

States a specific verb and resource ('Resolve the browser setup link for a standalone order connection') and immediately differentiates itself from siblings by declaring what it does NOT do (create a connection, save credentials, start OAuth), which separates it from configure_order_connection. An agent can distinguish it without opening any schema.

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

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

Names the prerequisite source (a channel from list_order_channels) and the exact follow-up tools (get_order_overview, test_order_connection, configure_order_connection), and tells the agent which branch to take on each status outcome. Explicit when-to-use and when-not-to-do-something guidance is present.

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

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

Annotations only 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?

Goes well beyond the destructive/idempotent annotations: it discloses the confirm_required error gate, the addon_required 403 refusal, that custom_<code> values persist until the next full import, and project_id inference. This is exactly the extra behavioral detail annotations cannot convey.

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

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

Front-loaded with the DESTRUCTIVE warning, then the gate, addon, and return shape in a logical order. It is dense and mostly earns its place, though a few clauses (e.g., the trailing URL note) add length without being essential to this call.

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, entitlement-gated mutation with no output schema, the description supplies the confirmation protocol, failure modes, persistence caveat, and return shape ({status, code, applied}). An agent has everything needed to call it correctly.

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

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

With 0% schema coverage, the description carries the full burden and does: code drives the deletion, confirm:true is the safety gate, apply:true triggers re-import, and project_id is optional/inferred. All four parameters are given meaning 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?

States a specific verb (Remove), resource (AI source), scope (its CSV + registration), and the consequence (no longer applied on future imports). This clearly distinguishes it from siblings like delete_api_source 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?

Gives strong operational context: confirm with the user first, the confirm:true gate, apply:true to re-import now, and the addon prerequisite. It does not explicitly compare against the closest alternatives (e.g., set_ai_source or delete_api_source), so it stops short of full when/when-not routing.

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

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

Goes well beyond the annotations: it discloses the confirm gate and where it is enforced, the exact error codes (confirm_required, addon_required/HTTP 403 with addonCode), entitlement requirements, the deferred-clear behavior of apply, and the response shape. Multiple safety- and auth-relevant behaviors are surfaced that annotations alone could not convey. No contradiction with destructiveHint=true.

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

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

Dense but every sentence carries a distinct, load-bearing fact (gate, error, entitlement, apply timing, return value). Purpose leads, though the destructive warning and the entitlement note are somewhat interleaved rather than cleanly ordered.

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

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

For a destructive 4-parameter mutation with no output schema, the description supplies the return value ({status:'deleted', code, applied}), the failure modes, and the entitlements needed. An agent has everything required to call it correctly and handle refusals.

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

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

Schema description coverage is 0%, so the description must carry the burden and it does: `code` is the attribute key, `confirm` is the destructive gate, `apply` controls immediate re-import vs deferred clear, and `project_id` is optional and inferred for single-project customers. All four parameters gain meaning 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?

States a specific verb (Remove), resource (API source attribute), keying field (`code`), and scope (from every product so it is no longer applied). An agent can distinguish this from delete_ai_source and set_api_source purely from the name plus the described scope.

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

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

Gives strong call-time guidance: confirm with the user first, call with confirm:true, and what happens otherwise (confirm_required error, nothing deleted). Also states the addon prerequisite and explicitly says not to retry. It lacks explicit contrast with sibling alternatives (e.g. delete_ai_source, set_api_source), which keeps it 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?

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?

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them by disclosing the cascade (feeds/channel profiles hard-deleted, webhooks unregistered), the absence of a restore path, and the exact guard-rail error and HTTP status. That is precisely the extra behavioral detail annotations cannot carry.

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

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

The destructive warning is front-loaded and every sentence carries information, but it is a single dense block that packs cascade effects, error codes, and parameter sourcing into one run-on passage. Slightly restructured line breaks would improve scanability 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?

Although there is no output schema, the description supplies the return shape ({integrationId, action:'delete', status:'deleted', kind}) and covers preconditions, confirmation flow, and fallback lookups. Nothing an agent needs to invoke this safely 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 carry the load and does: it explains where marketplace_id comes from, that project_id is optional with a named failure condition, and that confirm is a required-for-success boolean whose absence yields a specific 400 error. Zero-coverage parameters are fully compensated.

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

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

States a specific verb and resource ('Delete a marketplace') and immediately scopes what deletion means in practice: stops syncing, removed from the list, hard-deletes feeds, unregisters webhooks. This separates it from sibling deletes like delete_feed, delete_ad, and delete_rule, which act on narrower resources.

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 instructs to warn the user, confirm first, then call with confirm:true, and states the failure mode (error 'confirm_required', HTTP 400, nothing deleted) if confirm is omitted. It also routes parameter sourcing: marketplace_id from list_marketplaces and project_id from list_projects when project_id_required, with the single-project inference case named.

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

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

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context: Rules patch feed output only and write nothing to products, the guardrail against keyword-matching rules, and the left-to-right chaining semantics where returnType must match the next op's valueType.

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

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

Purpose and the 'call FIRST' directive are front-loaded, and every clause carries real instruction. However, the dense return-shape and recipe references arrive as one long run-on block, making it harder to scan than it needs to be.

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

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

No output schema exists, but the description spells out the full return shape (operations, conditions, ruleSchema, examples) and points to the knowledge slug for the authoring recipe. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 0%, so the description must carry all four params — and it does: `group` filters to one operation group, detail 'full' vs 'compact' (default), include_conditions adds condition operators, include_examples adds worked examples. This fully compensates for the empty schema.

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

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

States a specific verb (discover) plus resource (rule operations vocabulary) and defines the domain in the user's own language ('Attribute Rules' / 'Rules'). It is unmistakably distinct from siblings like create_rule, validate_rule, and get_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?

Explicitly instructs 'Call this FIRST, before you write a rule' and adds a hard exclusion: if a value needs more than 3 contains conditions, stop and use set_api_source/set_ai_source instead. It also routes to validate_rule before create_rule/update_rule and names koongo_knowledge for the authoring recipe.

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?

Adds substantial behavior beyond the annotations (destructiveHint=true, idempotentHint=false): exact return shape, that queued status is normal async behavior, that regeneration replaces output files already pulled by channels, and that API feeds may auto-submit. This is exactly the kind of impact disclosure the annotations cannot convey.

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

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

Front-loaded with the action, then return shape, then workflow, then caveats. Dense but every sentence is informative; the embedded JSON return description makes it slightly heavier than ideal but not wasteful.

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 documenting the return payload and status values, plus the downstream polling step and the destructive side effect. An agent has everything needed to call it and reason about consequences.

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 the load. It states feed_id comes from list_feeds/create_feed and that project_id is OPTIONAL, which is useful provenance, but adds no format, constraint, or interpretation detail (e.g. what project_id scopes). Partial compensation for the coverage gap.

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

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

States a specific verb+resource: 'Trigger a (re)generation of the feed file.' An agent knows exactly what the tool produces. It does not explicitly distinguish itself from close siblings like submit_feed or get_feed_output, so it falls short of a 5.

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

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

Gives clear usage context: trigger, then poll get_feed_status until 'generated', and explicitly instructs the agent to confirm the destructive effect with the user first. It names the follow-up tool but never states when to prefer this over submit_feed, so no explicit exclusion/alternative routing.

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

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

Annotations declare readOnlyHint=true and this description honors it, while disclosing a rich behavioral caveat the read itself implies: activationBehavior values encode side-effects that the wizard can trigger (summary_step_activates_and_submits_all publishes all products to the LIVE channel and spends budget). Also discloses optionsPending semantics, the auth-step exception, one-connection-per-ad, secrets never returned, and read-only taxonomy. Annotations cover the read safety of the tool itself; the description flags downstream effects the caller must know.

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

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

Front-loaded with the essential verb+resource and the critical activationBehavior warning, but the body is a dense run-on covering activation behavior, return shape, wizard step semantics, field schema mechanics, auth-step exceptions, connection ownership, taxonomy, secrets, and parameter notes without paragraph breaks or headers. Every sentence earns its place, but the structure is hard to scan.

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 tool with no output schema and complex nested wizard-step returns, the description supplies the full field inventory, step semantics, field-schema mechanics for building configure_ad_step payloads, the auth-step terminal behavior, and connection/taxonomy semantics. Nothing an agent needs in order to call it correctly and interpret its result 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 carry the load. It does a lot: ad_id is the id from list_ads/create_ad, project_id is optional and inferred for a single-project customer, and project_id_required otherwise (then call list_projects). The remaining gap is that project_id's exact relationship (do you pass it always?) isn't completely nailed down, but the semantics are meaningfully covered.

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 (get) and resource (one ad), and explicitly enumerates what it returns: identity, state, wizard steps, and a full field list. It also carves out the ads-vs-marketplaces distinction and contrasts with sibling ad_status ('Use get_ad for configuration and ad_status for run progress'). This is well-differentiated 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?

Explicit when-to-use and when-not-to-use: route to ad_status for run progress, set MANUAL mode first before testing, complete auth in browser not MCP, never retry the connection step with a payload. Names alternative tools (list_ads, create_ad, configure_ad_step, list_projects, test_ad_connection).

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 readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: the valueSource enum semantics, that ruleEnabled=false makes an attribute read 'unmapped', the currency double-conversion pitfall, and the warmup provisional-count caveat. It does not cover pagination or auth, but the behavioral depth here is well above the annotation floor.

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

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

One dense run-on block of sentences mixing purpose, schema field enumeration, workflow, edge cases, and warnings. The 19-field return-value listing and currency aside bloat the description and bury the critical warmup warning at the end rather than front-loading it.

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

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

No output schema exists, so the description must carry return-shape burden, and it does enumerate the return object. It covers the complex warmup lifecycle, mapping workflow, and value-source semantics thoroughly. Slightly heavy, but complete for a complex read tool.

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

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

Schema coverage is only 33%, so the description compensates: it explains ad_id's source, project_id's optionality and fallback, and only_unresolved:true's filtering behavior. This meaningfully exceeds what the schema alone documents, though it could be tighter.

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 an ad's OUTPUT attributes and how each is currently sourced') and explicitly frames it as the tool for solving the attribute form, distinguishing it from siblings like get_ad, get_attribute_options, or map_ad_attribute. The response schema enumeration further sharpens the 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?

Names the next action (map_ad_attribute) and where the ad_id comes from (list_ads), explains project_id optionality, and prescribes an entire workflow for the warmup case ('poll ad_status until the block is absent... then read this again'). Includes both when-to-use and when-not-to-trust (the provisional warning).

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the description focuses on operationally useful behavior: the ads-vs-marketplace distinction, the conditional project_id inference, and the project_id_required failure path. It stops short of stating pagination or any per-call limits, but for an idempotent read that is minor.

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

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

Front-loaded with purpose, then return payload, then the call-ordering guidance, then parameter notes. Every sentence carries information, though the dense inline return-shape enumeration makes it longer than typical and slightly harder to scan.

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 full burden of describing the return: field list including definitions[].capabilities and the versionType primary/secondary semantics. Combined with parameter sourcing and call-order guidance, nothing an agent needs to call and interpret this tool 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 50% (only channel_code documented). The description compensates by explaining channel_code's origin (list_ad_channels), project_id's optionality and inference behavior, and the fallback path when it is required. That is meaningfully 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+resource ('Get one ad channel's detail') and immediately scopes it: integration types plus each type's capabilities. It also distinguishes ads channels from marketplaces ('they publish products to the ad platform and have no order sync'), which is essential given the sibling tools get_marketplace_channel and get_ad coexist.

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

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

Explicitly states the trigger and the downstream action: 'Call this before create_ad to choose the right definitionCode for the channel.' It also names where inputs come from (channel_code from list_ad_channels; project_id via list_projects) and the condition under which project_id becomes required (project_id_required for multi-project customers).

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond them: entries are process metadata only (no raw product values), an item with no activity returns an empty list, and results are newest-first. Auth/rate-limit behavior is not mentioned, keeping it short of a 5.

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

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

Front-loaded with the core purpose, then the return shape, then id provenance, then the optional-parameter caveat. It is a single dense paragraph but nearly every clause carries actionable information; the explicit field enumeration of the returned entries is slightly verbose.

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 carries the return contract, listing the returned object shape, the entries' fields and their raw-vs-label duality, the newest-first ordering, and the empty-list case. Combined with usage and id-provenance guidance, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 75% and the schema already documents ad_id and item_id origins. The description compensates for the undocumented project_id by explaining it is OPTIONAL and only required when project_id_required is set (then call list_projects). The limit parameter's default/max lives only in the schema and is not restated, which is acceptable.

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: 'Get ONE ad listing item's action-log timeline' and clarifies it covers the sequence of events on the product plus its Koongo/channel state. This clearly distinguishes it from siblings like get_ad_item_report (a report) and get_marketplace_item_history (the marketplace counterpart).

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 frames the diagnostic use case ('so you can explain WHY an item ended in its current state'), names the source of each id (list_ad_items, list_ads, list_projects), and instructs pairing with get_ad_item_report to diagnose a failing product. Alternatives and prerequisites are both covered.

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 cover readOnly/idempotent/no-destructive and say nothing about the sensitive two-phase gate. The description discloses the withheld currentValue on first call, the sensitiveGate.confirmationRequired:true response, the user-approval requirement, and the re-call with acknowledge_sensitive:true — real behavioral context that cannot be inferred from structured fields.

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

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

Front-loaded with purpose, then the semantic key, then the sensitive-gate procedure, then param provenance. It is dense and the long inline field enumeration is heavy, but most of it earns its place given there is no output schema to carry that load.

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 enumerates the returned fields and explains the raw-code vs display-label distinction, plus error source/level interpretation (export vs adapter/api_error) and the sensitive-value recovery path. An agent has everything needed to call it and interpret the response.

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% with ad_id, item_id and acknowledge_sensitive already documented in the schema. The description adds sourcing hints and, importantly, supplies the only guidance for the undocumented project_id ('OPTIONAL ... project_id_required otherwise — then call list_projects'), plus the semantics of raw codes vs human labels that affect interpretation of the results.

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

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

Specific verb+resource with an explicit scope qualifier ('full error report of ONE ad listing item') and a parenthetical that states what the payload answers (why the product passed/failed). It is readily distinguishable from siblings like get_ad_report and get_marketplace_item_report by the 'ad item' granularity.

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

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

Gives concrete prerequisites and provenance for each param (item_id from list_ad_items, ad_id from list_ads, project_id fallback to list_projects) and a clear when-to-call-again rule for acknowledge_sensitive. It does not explicitly say when to prefer this over get_ad_report or the marketplace counterpart, so routing between the three report tools is left to inference.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, and the description adds substantial context beyond them: the report is split into two groups with different sources ('export' vs 'adapter'/'api_error'), errorCount/warningCount are combined totals, export is async, and results are only meaningful after a generation. This is exactly the kind of operational detail annotations cannot convey.

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

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

Front-loaded with purpose, then return shape, then usage sequencing and parameter notes — a logical order. It is unusually dense and long, but nearly every clause (error sources, async polling, enum-ish value lists) carries information an agent needs; a small amount of compression could be achieved without loss.

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 no meaningful annotation detail beyond safety, the description fully compensates: it enumerates the return object fields and nested error structure, explains status/listing status count meanings, and clarifies how ad_id and project_id are obtained. Nothing critical for correct invocation 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 carry parameter meaning, and it does: ad_id is 'the id from list_ads,' and project_id is OPTIONAL, inferred for single-project customers, but project_id_required otherwise (calling list_projects to resolve). Both parameters are fully explained despite 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?

States a specific verb and resource ('Get the validation report for one ad') and immediately defines the payload as 'aggregated errors and warnings that block or degrade its feed, with fix suggestions.' It further disambiguates from the large sibling set by explicitly defining ads as ads-based channels 'not marketplaces,' so an agent can distinguish it from get_marketplace_report.

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

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

Gives explicit preconditions and sequencing: data-check errors exist only after a generation has run, so the agent should finish the wizard or call repair_ad, then poll ad_status until productsRefreshing and productsSubmitting are false. It also names concrete alternatives (repair_ad, configure_ad_step, list_ads, list_projects) with the conditions that select them.

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

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

Annotations already cover readOnly/idempotent/non-destructive. The description adds context beyond that: the return shape, that the stored value is the option's `value` not its label, pagination behavior, and the branch when options are empty. It's richer than the annotations, though it doesn't discuss auth or rate limits.

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

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

Content is dense and front-loaded on the core purpose, but the description is a long run-on paragraph mixing return format, two application strategies, pagination, target selection, and project_id handling. It's information-rich but not well-structured; splitting into short labeled sentences would improve scanability.

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 the return shape {options:[{value,label}], hasMore, nextOffset}, pagination, the empty-result branch, target parameter rules, and how to act on the result. An agent has everything needed to call and interpret it.

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

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

Schema coverage is already 80% (all params documented). The description adds meaning beyond the schema by clarifying the EXCLUSIVE-OR between feed_id and integration_id, the source of attribute_code, project_id being optional/inferred, and offset pagination semantics. It 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?

States a specific verb and resource ('Get the allowed OPTION choices (value + label) of a target feed/channel attribute') and explains the downstream purpose (picking a valid value for a Set option). It distinguishes itself from siblings like get_feed_attributes and set_value by scoping to closed-option (select/dropdown) 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?

Explicitly says when to use it (to pick a valid value for a Set option), names alternatives (map_feed_attribute / map_marketplace_attribute / map_ad_attribute for unconditional, setoption rule for conditional, set_value for free text), and gives the 'Empty options = not a closed-option attribute' exclusion. This is exceptional routing guidance across multiple siblings.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld=false), so the bar is lower. The description goes further with the non-obvious SHARED-ness semantics ('every feed on that taxonomy sees it') and an inline description of the return shape, which materially affects how an agent interprets the result.

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 scope, then addressing modes, then return shape, then sibling routing — every sentence carries information. It is dense (long parenthetical return summary), but nothing is redundant 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 4-param read tool with no output schema, the description covers addressing modes, the shared-rule scope, and even the returned fields (taxonomyCode, taxonomyLocale, rules[], total), so an agent can call and interpret it without extra docs.

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%, but the description compensates: it explains feed_id vs taxonomy_code as mutually alternative addressing paths, notes taxonomy_locale defaults to the taxonomy's own default, and marks project_id as optional/inferred. This adds real 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?

States a specific verb+resource ('Get the current category-mapping rules for a taxonomy') and immediately defines the domain mapping (store categories → marketplace/taxonomy categories). It also names the exact scope (per project + taxonomy_code + locale) that separates it from sibling rule-listing 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?

Explicitly names alternatives with conditions: 'Use list_unmapped_categories to find gaps, search_target_categories to find a target, and set_category_mapping to fill them.' It also states the two accepted addressing modes (feed_id OR taxonomy_code+locale) and that 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 only cover the read-only/idempotent safety profile, and the description far exceeds that: hidden=true semantics, valueSource enum meaning, enabled-vs-disabled rule behavior, price/currency double-conversion warning, requiredUnmappedCount interpretation, and the 'feed_deleted' error contract for soft-deleted feeds. This is rich behavioral context beyond structured fields.

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

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

Purpose is correctly front-loaded, but the body is a single dense paragraph with a long inline field dump. Given no output schema, return-shape explanation is warranted, yet the packaging is hard to parse and could be segmented rather than delivered as one wall of 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?

Given a read-only 3-param tool with no output schema, the description covers return shape, edge cases (soft-delete, disabled rules, currency), prerequisites, and sibling routing. Nothing material 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 coverage is only 33% (just response_format documented), so the description must compensate and does: feed_id is 'the id from list_feeds / create_feed' and project_id is OPTIONAL/inferred, with list_projects named when required. Only response_format's two modes are left to the schema, so it adds clear meaning.

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

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

States a specific verb+resource ('Get the full detail of one feed') and enumerates the scope: identity + state + attribute mapping. It clearly differentiates itself from get_feed_status, get_feed_output, list_feeds, and even update_feed in the sibling set.

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

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

Explicitly routes the agent: 'Use get_feed for configuration/mapping and get_feed_status for run progress,' names map_feed_attribute/list_source_attributes for the next step, and states prerequisites (dataStatus='ok'). It also handles project_id optionality and the soft-delete/restore path, so when-to-use is fully covered.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds real behavioral context the annotations cannot: the sensitive-data gate requiring acknowledge_sensitive:true after user approval, and the reduced first-call response with an empty sample. However, because the read-only/idempotent traits are fully carried by annotations, the marginal descriptive contribution is moderate rather than exceptional.

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

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

Front-loaded with purpose and contrast to export_feed, then metadata, then the gate workflow. It is a dense wall of text that repeats offset/sample_size defaults already in the schema, but with no output schema the return-value listing is legitimate content, so most sentences earn their place.

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

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

No output schema exists, and the description fully enumerates the return shape ({feedId, projectId, feedUrl, productsCount, lastGeneratedAt, sample...}) plus the special gate response. Combined with the fileExists:false recovery path and the two-phase sensitive flow, an agent has everything needed to call 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 coverage is only 60%, so the description must compensate, and it does: it explains feed_id's origin (list_feeds/create_feed), project_id's optionality and the project_id_required fallback via list_projects, sample_size default/max, offset paging semantics (steps of sample_size), and the acknowledge_sensitive gate behavior. This adds meaning well beyond the two schema-described params.

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

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

States a specific verb and resource ('read the CURRENT output of a feed's already-generated file') and immediately distinguishes itself from the sibling export_feed, noting it does NOT regenerate. An agent can route between get_feed_output and export_feed without opening either schema.

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

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

Explicitly names when to use it (see a feed's live URL, product count, sample rows without downloading) versus the alternative (export_feed regenerates and is a write action). It also gives conditional guidance: project_id inference rules, what to do on fileExists:false (call export_feed then poll get_feed_status), and the two-call sensitive-gate flow.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered, but the description goes well beyond them: it discloses the enumerated status alphabet, the meaning of 'overlimit', the recommended polling behavior for processing/pending, and the error recovery path. It also documents the inferral behavior of project_id (optional for single-project customers, required otherwise), which is behavioral context no annotation provides.

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

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

Front-loaded with purpose, then return shape, then status semantics, then parameter notes — no sentence is wasted. It is a dense wall of text rather than scannable structure, which costs it a point, but 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?

There is no output schema, so the inline return-field list and status enum are necessary and present. Combined with next-action guidance, sibling differentiation, and parameter provenance, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: feed_id is defined as 'the id from list_feeds / create_feed', and project_id is explained as OPTIONAL with the inference rule and the fallback action (call list_projects) when project_id_required. This is meaning the schema's bare integer types cannot 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 ('Get the runtime status of one feed') and enumerates the exact facets returned: generation state, progress, last run/submit, and error. It further differentiates itself from the sibling get_feed by contrasting 'run progress' against 'configuration/mapping', so an agent can select it without opening either schema.

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

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

Explicitly names the alternative ('Use get_feed for configuration/mapping and this tool for run progress') and gives a full when-to-do-what decision table keyed on status: generated → verify_feed_attributes then submit_feed; processing/pending → keep polling; error → fix + export_feed; overlimit → plan limit. This is explicit routing rather than implied usage.

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, idempotentHint, destructiveHint=false, but the description adds substantial behavioral context beyond them: the full return shape (including nested lastRun and recentRuns), status enum meanings, the rule that mapping should only occur when dataStatus='ok', and the polling semantics for enrichment imports. This is exactly the kind of extra detail that helps an agent use 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 well-structured and front-loaded: purpose first, then return shape, then status semantics, then usage workflows. Every sentence earns its place—even 'lastRun is the newest of them' clarifies a non-obvious relationship. 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 one optional parameter, no output schema, and rich annotations, the description is complete: it explains the return data, status enums, polling workflow, error recovery, and next steps. An agent has everything needed to call it correctly and interpret the result without external documentation.

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

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

Schema coverage is 0% for the single project_id parameter, so the description must compensate fully. It does: 'project_id is OPTIONAL (inferred for a single-project customer; project_id_required otherwise — then call list_projects)'. This explains the optionality, the fallback condition, and the recovery action, adding complete meaning beyond the bare schema 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 states a specific verb and resource: 'Check whether a project's store data is connected, imported and fresh'. It distinguishes from siblings like get_feed_status by clarifying it's about project-level store import status before feeds/mapping, and it even names the follow-up tools (preview_products, list_feed_templates). An agent can tell what this tool does without opening the schema.

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

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

Provides explicit when-to-use: 'before advising on feeds/mapping', and when to poll: 'after set_api_source/set_ai_source with apply:true (or run_import), poll here until the newest run of that type has running:false and status 'ok''. Also gives error handling ('run_import to retry') and next steps ('proceed to preview_products then list_feed_templates'). 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?

Despite readOnlyHint=true, the description adds substantial beyond-annotation context: the critical activationBehavior warning (SUMMARY step activates and spends budget), the safe-testing guidance to set MANUAL mode first, the auth step not being configurable via MCP, taxonomyCode being read-only, and caching caveats across the auth step. These are strong value-adds.

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 purpose is good, but the description is a dense wall of text with mixed concerns (activation warning, return schema enumeration, caching, auth, read-only notes, knowledge lookup, parameter provenance). Some of the return-field enumeration duplicates what an agent would discover. Could be trimmed.

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 and low schema coverage, the description carries the return shape and step/field semantics thoroughly, covers connection/auth limits, points to koongo_knowledge for deep reference, and handles the activation risk. Complete for a complex read tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains marketplace_id provenance and project_id's optional/inferred behavior plus project_id_required path — meaningful, but the two integer parameters are simple and the schema's exclusiveMinimum is not addressed. Marginal coverage, not full compensation.

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 ('Get the full detail of one marketplace') and enumerates exactly what is returned: identity, state, and the configuration wizard steps. This is clearly distinguishable from siblings like list_marketplaces (plural listing) and 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?

Provides explicit sequencing guidance: use marketplace_id from list_marketplaces/create_marketplace, note that project_id is optional and inferred for single-project customers. It doesn't explicitly name competing siblings to avoid, but the context of when to call it is clear.

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

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

Annotations already declare a safe read (readOnlyHint, idempotentHint, non-destructive), and the description adds substantial context beyond them: the ruleEnabled=false pitfall where a rule silently reads as 'unmapped', the currency double-conversion trap, the configured/stepField/default precedence and the warning that a step override 'beats the step for good', and the provisional-count caveat during category warmup. These are exactly the traps annotations cannot express.

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 workflow before descending into field semantics, and nearly every sentence carries operational value rather than filler. It is nonetheless a very dense block that enumerates roughly twenty return fields inline, which is heavy for a single paragraph and slightly harder to scan than it needs to be given there is no output schema to carry that load.

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 the return payload and does so field-by-field (valueSource enum, priceAttribute/currency semantics, requiredUnmappedCount, unresolvedCodes) plus the warmup state caveat. For a complex, workflow-coupled mapping tool this is complete enough to call correctly on the first try.

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% (one of three params documented), so the description must compensate and does: only_unresolved is explained as returning just the REQUIRED-but-unresolved rows, marketplace_id is sourced from list_marketplaces, and project_id's optionality plus the project_id_required fallback to list_projects is spelled out. No parameter is left ambiguous.

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

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

States a specific verb+resource ('List a marketplace's OUTPUT attributes and how each is currently sourced') and frames the tool's job sharply as 'SOLVING THE ATTRIBUTE FORM'. This is far more specific than a tautology. It does not explicitly contrast itself with the closest siblings (get_ad_attributes, list_source_attributes, get_category_mapping), so an agent must infer the marketplace vs. ad-channel distinction rather than being told.

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

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

Explicitly names when to use it (solving the form, resolving requiredUnmappedCount/unresolvedCodes), the immediate follow-up (map_marketplace_attribute to fill one, configure_marketplace_step to change a step-driven value), and the prerequisites (marketplace_id from list_marketplaces; project_id optional or list_projects when required). It also states a when-NOT-to-trust condition: with pending warmup the list is incomplete, so poll marketplace_status first.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-openWorld). The description adds real behavioral value beyond that: it enumerates the returned payload shape (channelCode, label, kind, definitions with capabilities), clarifies that kind is always 'marketplace', and explains versionType/primary semantics. This meaningfully compensates for the absence of an output schema.

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

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

Front-loaded with the core purpose, followed by return shape and then parameter/usage notes — a logical order. The inline JSON return-shape block is dense but justified by the lack of an output schema; otherwise efficient, with only minor redundancy in restating capabilities.

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, 2-parameter tool with no output schema, the description covers everything an agent needs: what it returns (including field-level semantics), when to call it, and how to supply both parameters. 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 coverage is only 50% (channel_code is described, project_id is bare), yet the description compensates: it explains channel_code's origin ('from list_marketplace_channels') and fully characterizes project_id's optionality and fallback ('inferred for a single-project customer; project_id_required otherwise'). This adds semantics 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?

States a specific verb+resource ('Get ... the integration TYPES it supports and each type's capabilities') scoped to ONE marketplace channel. The scoping word 'ONE' implicitly distinguishes it from the sibling list_marketplace_channels, and the named downstream use (before create_marketplace) separates it from get_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?

Explicitly states when to call it ('Call this before create_marketplace to choose the right definition for the channel') and documents the dependency chain (channel_code from list_marketplace_channels, project_id from list_projects when required). No explicit when-not-to-use case or named alternative tool, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld=false), so the marginal burden is low. The description does add real behavioral context: entries arrive newest-first, labels versus raw codes are both returned, and entries are process metadata only with no raw product values. It stops short of describing pagination semantics, truncation behavior, or what happens when an item has no history.

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

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

Purpose is front-loaded and every clause does work, but the middle run-on sentence packs the return shape, three label/raw-code pairs, and a metadata caveat into a dense block. Line breaks or a short structured list would have improved scanability 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?

There is no output schema, and the description compensates fully by inlining the return shape ({itemId, returned, entries:[...]}) with every field named, plus the meaning of the label fields. Combined with ID provenance and the sibling-tool workflow, an agent has everything needed to call this correctly on the first attempt.

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 item_id, marketplace_id, and limit. The description adds genuine meaning the schema lacks: project_id is optional/inferred, and both required IDs have named source tools. However, the limit parameter's interaction with the timeline (default 20, max 50) is left entirely to the schema, and no filtering or ordering semantics for it are added.

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 ('Get ONE listing item's action-log timeline') and adds the scope qualifier 'ONE' plus the outcome it enables ('explain WHY an item ended in its current state'). The enumerated event vocabulary and the explicit contrast with get_marketplace_item_report make it distinguishable from the many sibling get_*_report 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?

Names the companion tool and the condition for pairing it ('Pair this with get_marketplace_item_report (current errors) to diagnose a failing product'), and explains the project_id prerequisite including the fallback ('inferred for a single-project customer; project_id_required otherwise — then call list_projects'). ID provenance is given for every required 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 establish that this is a safe, idempotent read, but the description adds material behavior on top: the sensitive-gate protocol (first call withholds currentValue and returns a sensitiveGate, user approval is required, then re-call with acknowledge_sensitive:true), plus the semantics of source, level, and human-vs-raw code fields. This is exactly the kind of behavioral context annotations cannot carry.

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

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

Purpose, return shape, gate flow, parameter provenance, and the sibling alternative are all front-loaded in priority order with no wasted sentences. The single dense paragraph enumerating every return field is justified given there is no output schema, though formatting it into distinct blocks would improve scanability.

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 return-value burden and does so by enumerating the payload fields and explaining the gate object. Combined with parameter provenance and the alternative-tool pointer, an agent has everything needed to invoke this correctly in one or two calls.

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 25%, so the description must compensate, and it does by giving provenance for item_id and marketplace_id, explaining project_id's optional/inferred behavior, and restating the acknowledge_sensitive gate. It adds routing value more than deep per-field semantics (e.g. no constraint notes), so it falls just short of a full 5.

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 detailed report for ONE listing item of a marketplace') and immediately scopes it ('why this product fails or warns on the channel'). It names the sibling it is not ('For the marketplace-wide breakdown use get_marketplace_report'), so an agent can distinguish it from get_marketplace_report and get_ad_item_report without opening a schema.

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

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

It explicitly routes the agent: item_id comes from list_marketplace_items, marketplace_id from list_marketplaces, project_id is optional/inferred or requires list_projects when project_id_required, and get_marketplace_report is named for the marketplace-wide case. When-to-use, prerequisites, and alternatives are all stated rather than implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: the two-group split of errors sourced from export vs adapter/api_error, the async generation dependency, and the required polling sequence. This is exactly the operational context an agent needs to call it 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 purpose and scoping are front-loaded, and the dense output-shape and fix-suggestion detail is largely load-bearing, but the single giant paragraph mixes return format, async caveats, and parameter notes with little visual structure, and side comments like '(as in the CP's two separate views)' add minor noise.

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 specifies the return shape (top-level counts, statusCounts, listingStatusCounts, dataCheckErrors, channelErrors and the per-error fields), plus the async precondition. Nothing an agent needs to invoke or interpret the tool 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 compensate, and it does: marketplace_id is defined as the id from list_marketplaces, and project_id is documented as optional/inferred with the project_id_required fallback and the list_projects remedy. Both parameters are fully disambiguated.

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 ('Get the validation report for one marketplace') and immediately scopes it as aggregated errors/warnings blocking listing, explicitly contrasting with the sibling get_marketplace_item_report for single products. An agent can distinguish this from all other report 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?

Gives explicit preconditions and alternatives: data-check errors only exist after a generation has run, so finish the wizard or call repair_marketplace, and because export is async, poll marketplace_status until productsRefreshing AND productsSubmitting are false before reading the report. It also names get_marketplace_item_report for the single-product case.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious data semantics: locked:true means a paid feature that cannot be set until unlocked, and options may be null until the connection is authenticated. It does not cover error behavior for a bad connection_id, but the added constraints are substantive.

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

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

Purpose and routing are front-loaded, and the long field enumeration substitutes for the missing output schema so it earns its space. The block is dense and could be tightened, but no sentence is pure 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?

With no output schema and only partial schema coverage, the description carries the burden and delivers: it enumerates the return shape, explains two tricky field semantics, and closes the loop with the sibling calls needed to go from overview to configuration. Complete for 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 coverage is only 50% (project_id is undocumented in the schema), and the description fully compensates: it states where connection_id originates and that project_id is optional with the exact conditional fallback when project_id_required is set. Nothing an agent needs to supply the parameters is missing.

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?

Starts with a specific verb+resource and scope: 'Full detail of ONE standalone order connection.' The word 'ONE' and 'standalone' implicitly distinguish it from get_order_overview, which is named as the source of the ID. An agent can tell what it retrieves 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?

Explicitly routes the agent: connection_id comes from get_order_overview, the returned orderConfigFields feeds configure_order_connection, and project_id behavior is spelled out with the fallback (call list_projects when project_id_required). Both the input source and the downstream consumer are named.

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

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

Annotations already declare readOnlyHint/idempotent/destructive=false, and the description adds real value beyond them: the full return shape, the meaning and enum values of orderStatus, the rule that a new connection only appears after the user finishes authentication in the Koongo UI, and the project_id inference 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?

Purpose is front-loaded in the first clause, but the inline enumeration of every returned connection field is verbose. It earns most of its length by substituting for an absent output schema, though it could be trimmed without losing routing 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?

With no output schema, the description carries the full burden of describing return values and does so thoroughly (counts, sync state, connections array). Combined with annotations covering safety, an agent has everything needed to call 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 coverage is 0% for the single project_id parameter, but the description compensates by explaining it is OPTIONAL, gets inferred for single-project customers, and that project_id_required triggers list_projects. That is meaningful semantics 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?

States a specific verb+resource (order dashboard) and scopes it precisely to standalone order connections (marketplaces without a product wizard), explicitly separating itself from get_order_connection which drills into a single connection. An agent can distinguish it from siblings like list_orders and get_order_connection immediately.

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

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

Gives explicit when-to-use ('Start here to see order state'), names the follow-up alternative ('then drill into one connection with get_order_connection'), and describes the project_id prerequisite path (optional when single-project, otherwise project_id_required and 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 declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real behavioral context beyond that: marketCategories is empty when uncategorised, null stats mean not-yet-computed, and metricsSyncedAt conveys freshness. It doesn't discuss failure/auth modes, so a 4 rather than 5.

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

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

Front-loaded purpose and usage, then a dense parenthetical of field semantics. It is longer than most definitions but nearly every clause adds operational meaning; the return-shape enumeration is arguably compact enough to keep.

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 shape, field meanings, units, and null/empty edge cases, and it links the result to the recommended next tools. An agent has everything needed to call it and act on the output.

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

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

Schema coverage is 0% and the single parameter is otherwise bare, so the description must carry the load — and it does, stating project_id is OPTIONAL but inferred only for single-project customers, otherwise required with a call list_projects. The schema's integer/exclusiveMinimum constraint is not restated, a minor omission.

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 ('Get a project's catalog product profile') and immediately scopes the intent (to recommend sales channels). An agent can distinguish this from list_projects, get_marketplace, or get_category_mapping without opening any schema.

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

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

Explicitly tells the agent what to do with the result (cross-reference list_marketplace_channels / list_ad_channels, propose only channels whose `available` is true, then walk the create/configure wizard) and what not to do ('Never invent channels'). It also routes the project_id fallback: call list_projects when project_id_required. When/when-not/alternatives are all covered.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false). The description adds useful behavioral context beyond annotations: the error behavior ('not_found' for unknown rule_id), project_id inference/requirement logic, and the verbatim round-trippability of rules[]. However, it does not discuss rate limits or other runtime constraints.

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

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

Front-loads the core action (get full definition, round-trippable), then the return shape, then rule structure, then scope, then error and project_id behavior. Efficient but dense; the nested rules[] shape description is long and slightly interruptive to the primary usage message.

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

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

For a single-resource read tool with no output schema, the description richly covers return shape, rule array structure, scope semantics, error case, and parameter fallbacks. An agent has everything needed to call it correctly.

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

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

Schema coverage is only 33%, so the description must compensate. It explains scope semantics ('project' default vs 'shared_template'), rule_id's origin (from list_rules), and project_id's optional/inferred vs required behavior. This meaningfully compensates for the low schema coverage, though rule_id's exact source of truth could be tighter.

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

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

States a specific verb+resource (get the full definition of one product/Attribute Rule) and precisely scopes it via 'one rule'. It clearly distinguishes itself from list_rules (which enumerates) and update_rule (which it explicitly references as the round-trip target).

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 explains the round-trip workflow (edit and pass back to update_rule), names sibling tools (list_rules, discover_rule_operations, list_projects), and specifies the fallback when project_id is required. When-to-use vs alternatives is directly addressed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds material behavior they cannot convey: it runs no AI and never writes, the sensitive-data gate returns empty sourceValues/alreadyMapped on the first call and real values only after acknowledge_sensitive:true, and unmapped values pass through unchanged. This is exactly the extra context the annotation bar leaves room for.

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

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

Purpose and the sibling exclusion are front-loaded, and the remaining sentences are information-dense rather than filler. It is nonetheless a long block that mixes output shape, gating, parameter guidance and workflow in one stream; a little structure would improve scanning.

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

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

For an 8-parameter tool with no output schema, the description supplies the return shape (sourceValues/targetAllowedValues/alreadyMapped/hasMore/nextOffset), the two-step sensitive gate, the exclusive target choice, pagination, and the full rule-creation workflow. Nothing needed 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 coverage is 63% and the description compensates well: it explains that the attribute codes come from get_feed / get_marketplace_attributes / get_ad_attributes / list_source_attributes, clarifies the feed_id vs integration_id choice and its origins, and adds project_id inference logic ('inferred for a single-project customer ... then call list_projects'). The pagination and only_unmapped semantics largely duplicate the schema, so it sits just below 5.

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 ('Get the inputs needed to build a value-mapping rule that remaps a source attribute's values onto a target attribute's allowed set') and gives a concrete example. It explicitly distinguishes itself from the nearest sibling get_attribute_options ('to just assign ONE fixed value ... use get_attribute_options instead'), so an agent can route without opening either schema.

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

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

Names the when-to-use (value→value mapping via map_attribute_value), the when-not plus the alternative (Set option → get_attribute_options), and the downstream workflow (create_rule / update_rule, then map_feed_attribute / map_marketplace_attribute / map_ad_attribute with rule_id). It also states the fallback behavior for unmapped values.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior: context-saving purpose, the no-args/slug/query mode split, and per-mode return shapes. It does not say whether slug and query can be combined or what happens if both are supplied.

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

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

Front-loaded with the core purpose and the three modes, then the trigger conditions. The topic enumeration is long but earns its place by enabling selection without a round-trip; overall density is high with little 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?

With no output schema, the description compensates well by describing what each mode returns (slug+title+summary index; full body plus canonical help URL). Remaining gap is only the ambiguous both-parameters case, which is minor for a two-param read-only lookup.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does explain both parameters' semantics (slug = one topic's full body plus canonical URL; query = keyword search; no args = index). It stops short of stating the slug format or the precedence/behavior when slug and query are both given.

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 (fetch Koongo help/reference knowledge) and spells out three distinct invocation modes with their returns. It is the only knowledge/reference tool among the siblings, so differentiation is inherent and reinforced by the scope note that this content is kept out of always-loaded instructions.

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 to reach for it, naming the upstream tools whose output it helps interpret (list_*_items, get_*_item_report, *_status, *_report) and the four reference areas it covers. It also enumerates the available topics, so an agent can decide before calling.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavior beyond them: search + paging semantics (limit/offset, hasMore, nextOffset), the meaning of available=false with 'plan_limit' and 'appstore' reasons, and the invariant that orderSyncSupported is always false for ads. It does not restate annotation facts but enriches 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 opening sentence front-loads the core purpose and the disambiguation before detail. It is dense and somewhat long for a list tool — the embedded response-field enumeration ({channelCode, label, kind, ...}) is heavy — but every clause carries usable information, so it stays just this side of bloated.

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, and the description fully compensates by spelling out the response envelope ({channels, returned, total, kind, hasMore, nextOffset}) and per-channel fields, plus the availability/auth semantics. For a 4-parameter, zero-required list tool, 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 coverage is 75% and the schema already documents limit/query/offset. The description goes further by explaining the practical use of each (query matches channelCode/label, offset driven by response nextOffset) and by clarifying that project_id is OPTIONAL and inferred for single-project customers but triggers project_id_required otherwise, which the schema does not convey at all.

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 ads channels you can ADD — and immediately contrasts it with the sibling it is most easily confused with ('to list the ads that ALREADY exist, use list_ads'). It further scopes 'ads-based channels (advertising / price-comparison / classifieds), not marketplaces', so an agent can distinguish it from list_marketplace_channels and list_order_channels without opening any schema.

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

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

It explicitly names when to use this versus alternatives (list_ads for existing ads, get_ad_channel + create_ad as the downstream flow), and documents the conditional next step when project_id is required (call list_projects). That is a full when/when-not/next-step routing guide.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real beyond-annotation context: bulk channels yield an empty list rather than an error, rows carry only identifiers plus statuses with no attribute gate, and full values/error reports require get_ad_item_report. It also documents the project_id inference failure mode and the follow-up call required.

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

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

It is a single dense paragraph that front-loads the core purpose and return shape before filters and prerequisites. Every sentence carries information, though the run-on packing of return shape and routing hints slightly hurts 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?

With no output schema, the description compensates by listing the full return structure ({integrationId, total, returned, items:[...]}) with field names, plus filtering, paging, and downstream tool routing. Nothing an agent needs to call and interpret 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 coverage is 88% and already documents most parameters, but the description adds cross-tool semantics: itemId is the key to pass to get_ad_item_report/get_ad_item_history, ad_id is the integrationId from list_ads, and project_id's optional/inferred behavior. This meaningfully exceeds what the schema alone conveys.

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

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

States a specific verb and resource ('list the individual listing items of one ADS integration') and immediately scopes it to per-product listing-based channels, contrasting with bulk channels like Google Shopping. An agent can distinguish it from ad_status, get_ad_report, and get_ad_item_report without opening any schema.

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

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

Explicitly names when NOT to use it ('Google Shopping ... return an empty list; use ad_status / get_ad_report for those') and when to use it (filtering koongo_status/channel_status/listing_id/product_id to find failures). It also covers the project_id prerequisite ('inferred for a single-project customer; project_id_required otherwise — then 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: ads have no order sync, project_id being optional changes the result scope, the project_id_required error can occur, and the exact return shape is disclosed since no output schema exists.

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

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

The purpose and the key sibling distinction are front-loaded in the first clause. It is dense and the long enumeration of row fields is somewhat encyclopedic, but with no output schema those details earn their place and the structure remains scannable via parentheticals and clauses.

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

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

For a zero-mandatory-param list tool with no output schema, the description supplies everything needed: return envelope {integrations, returned, total}, full row shape, ads-vs-marketplaces semantics, optional-parameter behavior, and error handling. 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?

With a single parameter at 0% schema coverage, the description fully carries the load: it explains project_id is OPTIONAL, what happens with and without it ('that project's ads' vs 'across ALL your projects, each row carries its projectId'), and the error that triggers when it is needed. This far exceeds what the bare integer schema conveys.

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

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

States a specific verb+resource ('List the CREATED ads of a project') and explicitly contrasts itself with list_ad_channels ('not the catalog of channels you can add'). It also distinguishes ads from marketplaces and names the sibling tool to use instead, so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use and when-not-to-use guidance: use list_ad_channels for the channel catalog, and pass integrationId as ad_id to get_ad/ad_status. It also documents the project_id_required error path and points to list_projects as the remedy, leaving no inference 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?

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantive behavior beyond them: integration-managed feeds are excluded and only standalone feeds returned, results are not paginated, and an error token (project_id_required) with a recovery path is documented. This is behavior an agent cannot get from the annotations.

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

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

Front-loaded with purpose and sibling disambiguation, then item shape, then parameter semantics, then id relationships, then exclusions and pagination. The item enumeration earns its place because there is no output schema; every sentence adds information.

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

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

For a single-optional-param read tool with no output schema and full annotation coverage, the description is complete: it explains scope, return shape, exclusions, pagination status, and error handling. Nothing an agent needs in order 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 coverage is 0%, so the description carries the full burden and does so: project_id is OPTIONAL, its with/without semantics are spelled out (single project vs all projects), each returned item carries projectId, and the error token plus remediation is described. It also clarifies that feedId is the per-project id passed as feed_id, which the bare integer schema cannot 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+resource ('List the customer's CREATED feeds') and immediately disambiguates from the catalog sibling by naming list_feed_templates as the wrong choice. An agent can distinguish it from get_feed, list_feed_templates and list_projects without opening any schema.

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

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

Explicitly covers when to use it vs list_feed_templates, the conditional behavior of project_id (with/without), the error-recovery path when project_id_required is returned (pick a project via list_projects), and where feedId is consumed (get_feed / verify_feed_attributes). When-to-use, when-not, and alternatives are all named.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is lifted. The description adds real behavioral context beyond that: 'Returns all matching templates in one call; not paginated' and the project_id_required error condition. It does not describe rate limits or caching, but coverage is good.

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

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

Dense but front-loaded: identity, disambiguation, return shape, parameter guidance, and workflow all in order. Every sentence carries information; it runs long, but with almost 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?

With no output schema and 0% schema coverage, the description compensates by documenting the item fields, the unpaginated return, error behavior, and the downstream create_feed handoff. Nothing an agent needs to select or invoke it is missing.

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

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

Schema coverage is 0%, so the description carries the full parameter burden and does so: it explains project_id is optional and inferred for single-project customers (with the project_id_required failure mode), and warns that query must be a BROAD coarse filter, explicitly excluding country/format/language terms and redirecting matching to structured fields.

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

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

States a specific verb+resource ('List the PUBLIC Koongo feed TEMPLATES') and defines what a template is, including the return item shape {feedCode, name, type, ...}. It explicitly distinguishes itself from the sibling list_feeds ('These are NOT the customer's existing 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?

Gives explicit when-to-use routing: use list_feeds for existing feeds, use this for the creation catalog. It also prescribes the workflow (show matches, let user confirm feedCode, then call create_feed) and the recovery path when project_id is ambiguous (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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: searchable+paged behavior with default/max limits, hasMore/nextOffset contract, the meaning of available=false with its three availabilityReason values (plan_limit, appstore, fallback), and authType enumeration. This is rich disclosure not derivable from annotations.

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

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

Front-loaded with the core purpose and alternative, and nearly every sentence carries actionable detail. It is a long single block with heavy caps emphasis, which adds some visual noise, but little is truly 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?

No output schema exists, and the description fully specifies the response shape ({channels, returned, total, kind, hasMore, nextOffset}), per-channel fields, and the meaning of key flags. Combined with the workflow and paging contract, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 75% and the description compensates on the uncovered project_id, explaining the inference/required logic and the list_projects fallback. It also adds examples and match semantics for query ('channelCode/label', e.g. "amazon") and paging intent for limit/offset.

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 — searching the CATALOG of addable marketplace channels — and immediately distinguishes it from list_marketplaces (which lists existing ones). Names the exact set (Amazon, eBay, Kaufland, ...) so an agent can route without opening 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?

Explicit when-to-use with a named alternative ('to list the marketplaces that ALREADY exist, use list_marketplaces') and a downstream workflow (get_marketplace_channel for capabilities, then create_marketplace). Also states project_id is optional vs project_id_required, and to call list_projects in the latter case.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely non-obvious behavior: rows never carry raw attribute values, so no confirmation is needed here, whereas get_marketplace_item_report gates values behind a user confirmation. It also documents paging and the status-vs-channelStatus distinction.

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

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

Front-loaded with the resource definition and return shape, then filters and parameter guidance. It is dense and slightly overpacked in places (status/channelStatus explanation repeated around the return shape), but nearly every sentence carries usable routing or semantic information.

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

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

With no output schema, the description compensates by enumerating the returned fields and their meaning, plus the alternative tool, filter options, paging, and parameter sourcing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 75%, but the description adds real meaning beyond it: it explains status vs channelStatus semantics, that itemId is the value to pass as item_id elsewhere, that marketplace_id comes from list_marketplaces, and that project_id is inferred for single-project customers. It does not add syntax detail for the remaining filter params, so it stops short of a 5.

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 marketplace, the per-product rows'), and distinguishes it from list_marketplaces, list_marketplace_channels, and get_marketplace_item_report by describing exactly what a row is.

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

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

Explicitly routes the agent: use this for identifier/status rows, use get_marketplace_item_report for attribute values and error reports, filter with koongo_status/channel_status/listing_id/product_id 'to drive a fix', and it spells out the project_id fallback path (list_projects when project_id_required).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond annotations: the exact item shape, the response wrapper {integrations, returned, total}, and the project_id_required error-recovery path. It stops short of pagination/limit behavior, keeping it short of a 5.

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

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

Front-loads the core purpose and sibling disambiguation in the first sentence. It is dense — a long field enumeration and multiple conditional clauses — but every sentence earns its place. Slightly verbose field list keeps it from a 5.

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

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

For a read-only list tool with no output schema, one optional param, and no nested objects, this description covers scope, sibling disambiguation, parameter behavior, return shape, wrapper keys, and error recovery. 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 coverage is 0% and there is one optional parameter, so the description carries the full burden. It explains that project_id is OPTIONAL, what happens with and without it (single project vs. all projects, each item carrying its projectId), and connects integrationId to marketplace_id in downstream tools — rich semantics entirely absent from the schema.

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

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

States a precise verb and resource ('List the CREATED marketplace integrations of a project') and explicitly distinguishes itself from the near-identically-named sibling list_marketplace_channels, clarifying it returns existing integrations rather than the addable channel catalog. An agent can distinguish it from list_marketplace_channels, list_marketplace_items, etc., without opening 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?

Gives explicit when-to-use vs. the alternative (use list_marketplace_channels for the catalog), spells out the with/without project_id behavior, and provides recovery guidance for the project_id_required error (pick a project via list_projects). Nothing is left to inference.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral context beyond annotations: the exact return shape, the meaning of 'available' (false when the plan's order-connection limit is reached), the authType enum, and the project_id inference rule. Doesn't mention pagination, but a bounded channel list makes that less material.

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

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

Front-loads the core purpose, then the sibling routing rule, then the return contract and parameter notes. Dense but every sentence carries unique, actionable information.

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

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

Covers purpose, sibling routing, return structure, availability semantics, downstream usage, and parameter behavior. For a 2-param read-only list with no output schema, this is complete enough to call 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 coverage is 50%, with project_id lacking a schema description. The description compensates by explaining project_id's optionality and inference, and by describing the query filter; it also ties channelApiCode (from the response) to the next tool.

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

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

States a specific verb and resource ('List the marketplaces that can be added as a standalone ORDER connection') and crisply delineates the subset ('order-capable channels that do NOT have a product wizard'). It explicitly distinguishes itself from create_marketplace and routes to create_order_connection, so an agent can tell it apart from list_marketplace_channels and list_ad_channels.

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 when-to-use (order-capable channels without a product wizard) and when-not (channels with a wizard use create_marketplace) are both stated. It also names the downstream step (create_order_connection) and the fallback for missing project_id (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?

Goes well beyond the annotations (read-only, idempotent, non-destructive) by disclosing that PII fields are NEVER returned and that the free-text error reason is deliberately withheld because it may contain customer data. This is exactly the kind of behavioral context annotations cannot convey.

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

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

Front-loads the most decision-relevant fact (PII-free, sync-problem focus) and remains dense and largely waste-free. It is a long sentence cluster, but nearly every clause earns its place by resolving a real ambiguity.

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 no required parameters, the description compensates fully by spelling out the return object shape (orders array with named fields, total) and the syncStatus values. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 75%, and the description still adds meaning: it clarifies project_id is OPTIONAL here but required for the sibling list_projects, restates limit's default/max, and explains that connection_id is sourced from get_order_overview. This enriches beyond the schema's terse param descriptions.

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

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

States a specific verb (List) and resource (recent order records) scoped to the project, and immediately differentiates itself by emphasizing PII-free output and sync-problem spotting. An agent can place this against siblings like get_order_overview and sync_project_orders without opening a schema.

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

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

Gives a clear primary use case ('Best for spotting sync problems') with the concrete invocation (errors_only:true). It names follow-up routes for the optional project_id (call list_projects), though it could more explicitly contrast with get_order_overview for non-sync use cases.

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

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

Annotations cover read-only safety, but the description adds non-obvious behavior: empty lists can be misleading due to match-only accounts, broad searches are capped, and revoked/overlimit projects still appear. This is exactly the kind of operational context that annotations cannot express.

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, return shape, then usage. The field enumeration is necessary for an agent to interpret results. Dense but every sentence carries operational value; minor room for trimming.

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 1-param read-only listing with no output schema, the description covers return field semantics, apiStatus meaning, empty-result pitfalls, search caps, and next steps. 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 coverage is 100% and already documents `query`, but the description reinforces it with matching detail (name/code/email) and adds usage guidance (keep specific due to caps). Slightly above the baseline thanks to the cap warning.

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

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

Specific verb+resource: 'List your projects' with a documented return shape. It distinguishes itself from siblings by explaining its role as the entry point (call FIRST when you don't know which project) versus inference-based 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?

Explicit when: call first when project unknown, or when another tool returns project_id_required. Explicit when-not: single-project users usually don't need it. Names the alternative (inference) and the downstream tool (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 cover safety (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: the return shape, that usageCount is computed, that the query is a SUBSTRING match on NAME only and is coarse/non-unique, and that it's not paginated (returned === total). These details go well 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?

Dense but well-organized, front-loading the resource and return shape. Every sentence conveys distinct information. Slightly long, but no wasted 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?

Comprehensive for a read-only list tool with no output schema: it documents return structure, parameter behavior, filtering caveats, project_id resolution path, and pagination behavior. An agent has everything needed to call it correctly.

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

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

Schema coverage is 67% but the description compensates: it clarifies query semantics (case-insensitive substring on NAME only, non-unique) and scope enum meanings, and explains project_id's optionality and inference. Adds meaning beyond the schema.

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

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

States a specific verb (list) and resource (Attribute Rules) with explicit scope of what's returned. It distinguishes itself from sibling get_rule ('Use get_rule to fetch a rule's full rules[]'), making the relationship 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?

Explicitly directs to get_rule for full rule details, and explains project_id behavior including a fallback action (call list_projects when project_id_required). Scope values are documented with their meanings, giving clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the safety profile is covered; the description goes further by disclosing the return shape, that results are unpaginated (returned === total), the data-import prerequisite, and project_id inference behavior. Nothing material about behavior is left implicit.

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 the call-ordering rule, then the return shape and parameter conditions; nearly every sentence earns its place. It is still a dense single paragraph with heavy parentheticals, which makes it slightly harder to scan than it needs to be.

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-param read tool with no output schema, the description supplies return shape, pagination behavior, prerequisites, project_id resolution semantics, and the downstream call it feeds. An agent has everything needed to invoke it correctly without further exploration.

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 does: feed_id is explained as adding taxonomy parity with the feed editor, and project_id is explained as optional/inferred-or-required with the escape hatch (list_projects). This is meaning well beyond the bare 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?

States a specific verb+resource ('list the source attributes the store provides that a feed column can be mapped from') and immediately relates it to the sibling it feeds into, map_feed_attribute. The examples (brand, ean, price) make the resource concrete, so an agent can distinguish it from get_ad_attributes, get_marketplace_attributes and get_attribute_options.

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