Hustle Got Real

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the mutation and blast-radius profile is largely carried by structured data. The description adds useful context about why the confirmation flags exist ('pricing rules can affect many listings') and that the channel header is resolved internally. It still doesn't say what the rule will start doing to prices, whether it can be undone, or what the response contains.

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

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

Three short sentences, front-loaded with the action and scope, followed by the gating requirement. The final sentence is slightly compressed to the point of being hard to parse, but nothing is redundant.

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

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

For a destructive, non-idempotent, open-world write tool, the description covers the critical operational gate (both confirmation flags) and the channel resolution path. With an output schema present it needn't describe returns; the only real gap is the absence of any note on reversibility or on the update/delete alternatives.

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

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

Schema coverage is 100%, so the baseline is 3. The description corroborates that both confirmation booleans are required but adds no semantics beyond what the schema already says, and the closing phrase about 'HGRApi Header channel / ChannelOAuthId resolved internally' is ambiguous rather than clarifying the channelOAuthId 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 ('Adds a pricing rule') plus scope ('for one visible store'), which is enough for an agent to know what happens. It does not name the sibling pair it sits between (hgr_update_pricing_rule / hgr_delete_pricing_rule), so differentiation is implied by the create/update/delete naming rather than stated.

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 real prerequisite guidance: confirmed=true and impactConfirmed=true are mandatory, and hgr_list_channels is the source of channelOAuthId. It never says when to add a new rule versus modifying an existing one with hgr_update_pricing_rule, so the alternative-selection guidance is only implied.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is known. The description only reiterates the confirmation gate that the schema already documents, and says nothing about what the creation actually provisions (e.g., whether it is billable, sends an invite, or is reversible). It adds marginal context over structured fields, which fits a 3 with annotations present.

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

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

Two short sentences, both front-loaded and free of filler. Nothing is redundant or buried.

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, open-world creation tool, the description omits what a VA profile is, what the creation entails operationally, and any prerequisite state, even though annotations and output schema cover safety and returns. An agent could invoke it correctly mechanically but not confidently 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 description coverage is 100%, so both body and confirmed are already documented. The description restates confirmed=true but adds no semantics for the body payload beyond the schema's 'WAPI AddRequest body: Name.' Baseline 3 applies when the schema does the work.

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: 'Adds a Virtual Assistant / VA profile.' An agent can distinguish it from hgr_update_virtual_assistant and hgr_get_virtual_assistants by the verb alone. It doesn't explicitly name those siblings, 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?

There is no guidance on when to use this versus hgr_update_virtual_assistant or when a VA should be created at all. 'Requires confirmed=true' is a parameter precondition, not usage guidance, so the agent is left to infer the selection context.

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

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

Annotations already declare this as destructive, non-idempotent, and open-world, so the safety profile is largely covered. The description adds a valuable confirmation gate and notes internal channel resolution, but it does not explain what the status change actually does, what consequences are confirmed, or whether the change 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?

The description is three short sentences and front-loads the core action before prerequisites. The phrase about the HGRApi Header channel and ChannelOAuthId is slightly cryptic, but overall there is little 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?

An output schema, rich annotations, and full schema coverage reduce the description's burden. Still, for a destructive status-change tool, it omits the concrete effect of the change and the high-impact consequences the user must confirm, leaving a meaningful gap.

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

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

Schema description coverage is 100%, so parameter documentation is already strong. The description reiterates the confirmed/impactConfirmed requirements and mentions ChannelOAuthId resolution, but adds no semantics about valid AI Publisher status values or body contents beyond the schema.

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

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

The description states a clear verb and resource: 'Changes AI Publisher automation status for one visible store.' The single-store scope is useful. It does not differentiate this tool from nearby siblings such as hgr_update_ai_publisher_optimization or hgr_create_ai_publisher_agent, 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?

It gives prerequisites ('Requires confirmed=true and impactConfirmed=true') and scope ('one visible store'), which implies when the tool is applicable. However, it never states when to use this tool instead of alternatives or when not to use it, so usage guidance remains implicit.

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, openWorldHint=true, idempotentHint=false, so the risk profile is known. The description adds the two confirmation gates and that channel resolution is internal, but says nothing about what happens on a repeat call to an already-configured store — an important omission for a non-idempotent, 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?

Three short sentences, verb-front-loaded, no filler paragraphs. The final clause 'Requires HGRApi Header channel / ChannelOAuthId resolved internally' is jargon-heavy and partially redundant with the schema, but the definition is compact overall.

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

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

With an output schema and fully documented annotations, the description needn't explain return values, and it does cover the confirmation gates. It is still thin on the side effects of a destructive, non-idempotent create on a store that already has an AI Publisher agent configured.

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 each parameter already carries a detailed description, so the baseline is 3. The description restates the confirmation flags and adds 'ChannelOAuthId resolved internally', which mildly conflicts with the schema framing of channelOAuthId as a value returned by hgr_list_channels, so it does not add net clarity.

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 ('Creates/activates the default AI Publisher automation') and scopes it to 'one visible store', which is concrete. It does not distinguish itself from the nearby sibling hgr_change_ai_publisher_status, so an agent must infer which is the create path versus the status-toggle path.

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 prerequisites ('Requires confirmed=true and impactConfirmed=true') and points at hgr_list_channels as the source of channelOAuthId, which is a useful workflow hint. However it never says when to use this versus hgr_change_ai_publisher_status, nor what to do if an agent already exists, so usage is only implied.

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

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

Annotations declare a mutating, open-world, destructive operation; the description adds genuinely new behavior the annotations cannot convey: attachments are blocked by MCP policy and creation is gated on confirmed=true representing explicit user consent. It does not say what the response returns, but that is not its job here.

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

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

Three short sentences with zero padding, and the defining constraint (text-only) plus the blocking prerequisite (confirmed=true) are front-loaded where an agent will read them first.

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

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

With annotations covering safety profile, an output schema covering return values, and fully documented parameters, the description only needed the policy constraints and confirmation gate, which it supplies. A brief note on what happens after creation would push it higher.

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 both parameters are documented in the schema, including the semantics of confirmed. The description restates the confirmed requirement but adds no new format or content guidance for message, so the baseline 3 applies.

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

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

States a specific verb and resource ("Creates a text-only support ticket"), immediately separating it from read-side siblings like hgr_get_support_ticket and hgr_reply_support_ticket. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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 hard prerequisite ("Requires confirmed=true", meaning the user must have explicitly confirmed the message) and a scope limit (text-only). It offers no guidance on when to choose this over hgr_reply_support_ticket or hgr_get_support_ticket.

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 the description adds real value on top: it explains WHY the confirmation gates exist ('pricing rules can affect many listings') and that channel/ChannelOAuthId is resolved internally. It does not, however, say what state remains after deletion or whether the rule is recoverable.

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 and scope in the first sentence, followed by prerequisites. The trailing 'Requires HGRApi Header channel / ChannelOAuthId resolved internally' fragment is slightly jargon-heavy but earns its place by explaining an auth-resolution detail.

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

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

For a destructive 4-param mutation tool with full schema coverage and an output schema, the description covers what it does, the side-effect risk, and the required confirmation flow. An agent has everything needed to call it safely.

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

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

Schema coverage is 100%, so the boolean gates, body fields, and channelOAuthId are already documented. The description reinforces the confirmation semantics but adds little new detail on the body's RuleId/Active fields beyond what the schema states. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Deletes/deactivates a pricing rule') and scope ('for one visible store'), which clearly sets it apart from hgr_add_pricing_rule and hgr_update_pricing_rule. The dual 'Deletes/deactivates' wording is crisp enough but leaves slight ambiguity about which effect actually occurs.

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

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

The description implies usage through the confirmation prerequisites ('Requires confirmed=true and impactConfirmed=true'), but never explicitly says when to use this versus hgr_update_pricing_rule or hgr_get_pricing_rules. An agent must infer that deleting differs from updating the Active flag.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the risk profile is known. The description adds that channel context is resolved internally, but it never explains what 'force' overrides or what state is skipped/destroyed — the key behavioral fact for a destructive tool — and the phrase 'ChannelOAuthId resolved internally' mildly muddles the schema's required channelOAuthId parameter.

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

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

Three short sentences, front-loaded with the action and followed by prerequisites. No waste, though the terse phrasing ('Requires HGRApi Header channel / ChannelOAuthId resolved internally') is slightly elliptical rather than crisp.

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

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

An output schema exists and annotations cover the safety profile, so return values need not be described. However, for a destructive, non-idempotent mutation with many near-identical sibling tools, the description omits the consequences of forcing and any differentiation, leaving a real gap.

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

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

Schema coverage is 100% and each parameter carries its own description, so the description need only be a baseline. It mentions 'visible order Reference' and the confirmed flag but adds no semantics beyond the schema, such as whether reference is optional or how it interacts with channelOAuthId.

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: forcing processing of orders identified by a visible marketplace Reference. It is understandable on its own, but it never contrasts itself with the very similar siblings hgr_process_order_lines or hgr_manually_dispatch_order_lines, so an agent cannot tell which is right from the description alone.

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

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

The only guidance is the precondition 'Requires confirmed=true', which merely restates the schema's required flag. There is no statement of when to force versus normally process, no circumstances that justify the destructive 'force' path, and no named alternative.

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

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

Adds genuine context beyond annotations by clarifying the call only acknowledges a refresh request rather than producing an immediate stock or price change, and that channel/header resolution happens internally. However, with destructiveHint=true and idempotentHint=false declared, the description never explains what the refresh actually mutates on the marketplace or why it is non-idempotent, so the destructive profile is under-disclosed.

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

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

Three short sentences with the core caveat front-loaded; no filler. The telegraphic phrasing ('Requires HGRApi Header channel / ChannelOAuthId resolved internally') is slightly compressed but still parseable.

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

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

An output schema exists so return values need no explanation, and the confirmation caveat is present. But for a destructive, non-idempotent, open-world mutation, the description stops short of describing side effects, rate limits, or what a subsequent refresh state looks like.

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

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

Schema coverage is 100%, so parameters are documented in the schema; the description only restates confirmed=true and notes the channelOAuthId resolution is internal. It does not clarify the relationship or precedence between productId/productIds and variationProductId/variationProductIds.

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

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

States a specific action and resource ('Requests ForceRefresh for visible Product IDs'), which is distinguishable from listing-mutation siblings like hgr_relist_listing or hgr_remove_listing. The internal term 'ForceRefresh' is left undefined, but the scope (visible product IDs) is concrete.

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 requirement of confirmed=true implies the agent must have explicit user consent, which is a useful usage precondition, but the description never says when to prefer this over alternatives such as hgr_post_searchproduct_listnow, hgr_relist_listing, or hgr_update_listing.

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 real context beyond the readOnlyHint/idempotentHint annotations: output is plain CSV text rather than a file artifact, and there is a confirmed=true gate plus an internal channel/ChannelOAuthId requirement. These are meaningful behavioral disclosures an agent can't infer from annotations. It stops short of any size/rate limits or failure behavior, so not a 5.

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

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

Front-loaded with the core purpose and delivered in a few dense, useful sentences with no filler. The trailing 'Requires HGRApi Header channel / ChannelOAuthId resolved internally' is jargon-heavy and slightly muddled, keeping 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?

With an output schema present and 100% parameter coverage, the description only needs to establish output form and invocation gates, which it does. The one gap is the confusing channelOAuthId framing, which could make an agent wonder whether the value is supplied or resolved for 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 100% and each parameter already documents itself (including confirmed=true and productIds semantics), so the baseline is 3. The description adds only the emphasis that productIds must be explicit, but its 'ChannelOAuthId resolved internally' phrasing is ambiguous against the required channelOAuthId parameter, so it neither clarifies nor fully compensates.

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 (generates the limited product CSV) and immediately bounds it: 'the only product CSV allowed by MCP policy' and 'not a downloadable file.' It even enumerates the exact columns returned, so an agent knows precisely what this produces 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 prerequisites ('Requires explicit productIds and confirmed=true') and rules out the all-store export, which frames when this tool applies. No sibling in the list is a comparable CSV-export tool, so there is little alternative-routing to add; the exclusion of an all-store export is the key guidance and it's 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?

Adds real behavioral context beyond annotations: the MCP pre-checks current WAPI order status and fee data before executing, which tells the agent the call may be refused based on external state. The destructive/irreversible nature is already declared by destructiveHint=true, so omission there is acceptable, but the description never says what actually changes on the marketplace once tracking is generated.

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

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

Three short, front-loaded sentences with no filler; the precondition is stated before the confirmation requirement. Internal jargon ('HGRApi Header channel') costs a little clarity for minimal gain.

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, open-world mutation, the description covers preconditions but not outcomes: it does not say whether tracking generation marks the order line as dispatched or what failure looks like when WAPI disallows. The output schema carries the return shape, so that gap is excusable.

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

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

Schema coverage is 100%, so confirmation semantics for 'confirmed' and 'channelOAuthId' are already documented in the schema. The description only restates 'Requires confirmed=true' and notes the channel is resolved internally, adding little beyond that.

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 ('Generates HGR tracking') scoped to 'exact order lines' with a WAPI precondition. However, it never distinguishes itself from the nearly identical sibling hgr_post_sales_generatetrackingid or from hgr_set_manual_tracking_id, so an agent cannot route confidently between them from the description alone.

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

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

'when WAPI allows it' and 'Requires confirmed=true' imply preconditions, but there is no explicit when-to-use/when-not guidance and no named alternative for the manual-tracking path. The agent must infer selection from sibling names.

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

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

Beyond the annotations, it discloses an important response quirk: the payload can be a compact schema/data structure where rows are matched positionally to schema, and that this is not an error and does not need a second pass. It also notes the auth context ('Requires HGRApi Header channel / ChannelOAuthId resolved internally'), adding operational context not covered by annotations.

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

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

The purpose and store-resolution prerequisite are front-loaded, and most sentences carry operational value. It is dense and slightly sprawling with back-to-back directives, but the length is largely justified by the tool's complexity and ambiguity around source/origin fields.

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

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

Given 7 parameters, an output schema, and a non-obvious compact response format, the description covers everything an agent needs: store resolution, aggregation usage, source vs. origin semantics, response interpretation, export exclusions, and auth context. Nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic distinctions not present in the schema: 'source' means supplier/source marketplace, 'sourceId' is only for resolving visible supplier names, and 'origin' is the listing creation mechanism. It also explains that fields/sortBy/sortDirection/limit can be passed directly for aggregation.

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 ('Lists active listings') for a specific scope ('selected visible store/channel'). It distinguishes itself from siblings like hgr_get_listings, hgr_get_pending_listings and hgr_get_terminated_listings by naming the active-listing aggregation use cases it covers.

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 prerequisites ('First resolve the store with hgr_list_channels'), routing instructions for rankings/filtering/summaries, and a clear exclusion ('Do not use this tool to construct CSV, XML, XLSX, feed or bulk export files'). It also tells the agent which field to request for supplier questions and which field not to use (origin).

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so safety and idempotency are covered structurally. The description adds no behavioral context beyond the word 'Reads', such as what data the summary includes, authentication needs, 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?

The description is a single, front-loaded sentence with no filler or redundancy. It is appropriately sized for a zero-parameter read tool.

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

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

With zero parameters, rich annotations, and an output schema, the description need not explain return values or safety. However, it leaves ambiguity about how this dashboard summary differs from the monthly variant and other affiliate dashboard tools, which is a meaningful gap for an agent selecting among many siblings.

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

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

The tool takes zero parameters, so the schema is trivial and fully described. Per the rubric, a zero-parameter tool receives a baseline of 4 for parameter semantics.

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

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

The description states a specific verb (Reads) and resource (affiliate dashboard summary), making the basic action clear. It does not distinguish this tool from the closely named sibling hgr_get_affiliate_dashboard_monthly, so sibling differentiation is missing.

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

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

There is no guidance on when to use this tool versus alternatives such as hgr_get_affiliate_dashboard_monthly or hgr_get_affiliate_withdrawals. The description provides only a bare purpose statement with no usage context or exclusions.

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

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

The annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds no behavioral context such as default period, timezone, or what the summary aggregates, leaving the agent with only the word "Reads" beyond the annotations.

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

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

It is a single short sentence with no wasted words, but it is so terse that it fails to front-load the useful distinctions. Brevity here comes at the cost of clarity rather than from efficiency.

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

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

An output schema and annotations exist, so return format and safety need not be explained. However, for a tool with optional period parameters and a near-duplicate sibling, the description omits the default-period behavior and the sibling distinction that an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are documented in the schema as "Optional year/month number accepted by WAPI." The description adds no meaning beyond that; baseline 3 is appropriate when the schema does all parameter work.

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 verb and resource ("Reads affiliate monthly dashboard summary"), but it essentially restates the title and does not distinguish this tool from the closely named sibling hgr_get_affiliate_dashboard. An agent cannot tell from the description whether this is a subset, a different aggregation, or the same data scoped to a month.

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

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

There is no guidance on when to use this monthly dashboard versus hgr_get_affiliate_dashboard or hgr_get_dashboard_getaffiliatestatistics_period_from_to. Because year and month are optional, the description also omits what happens when they are omitted.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond them by naming the domain constraint (withdrawal-method changes must happen in HGRWeb), which prevents a doomed write attempt and gives the agent a redirect. It still says nothing about result volume or pagination, so not a 5.

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

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

Two short sentences with no filler, and the core purpose is front-loaded ahead of the constraint. Every sentence earns its place.

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

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

With no parameters, rich annotations and an output schema covering return values, the description only needs purpose plus any operational caveat — both are present. A note on whether the full history is returned unfiltered (since no filter parameters exist) would close the last gap.

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

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

The tool takes zero parameters and the schema is closed (additionalProperties: false), so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing filtering options that do not exist.

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

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

States a specific verb and resource: 'Reads affiliate withdrawal history.' An agent can immediately tell this is a read of withdrawal records and not a dashboard or token-history call. It does not explicitly name the nearest sibling (e.g., hgr_get_affiliate_dashboard or hgr_get_user_gettokenhistory), so it stops short of a 5.

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

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

The second sentence gives an implied boundary — mutations such as changing the withdrawal method are out of scope and belong in HGRWeb — which tells the agent when NOT to use this tool. However, it never states when to pick this over the many other affiliate/user read siblings, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is carried structurally. The description adds an auth/channel note ("Requires HGRApi Header channel / ChannelOAuthId resolved internally"), but that sentence is ambiguous about whether the caller must supply a channel header or whether it is derived internally, which is exactly the detail an agent needs.

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

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

Three tight sentences with the purpose and scope front-loaded. The trailing auth sentence is short but cryptic enough that it costs some clarity rather than adding 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?

A one-parameter read tool with full schema coverage and an output schema; the description need not explain return values. Purpose, scope, resource identity and the sibling-family distinction are all present, so an agent has enough 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 description coverage is 100% and the single parameter already points to hgr_list_channels as its source, so there is nothing left for the description to explain. The description adds no parameter 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 and resource ("Reads AI Agent configuration") scoped to "one visible store", and explicitly contrasts AI Agent with AI Publisher, which separates it from the hgr_get_ai_publisher_* family. It does not distinguish it from the closest sibling, hgr_save_ai_agent_configuration (write counterpart) or hgr_get_ai_agent_dashboard, 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?

There is implied guidance from "one visible store" and the AI Agent vs AI Publisher note, but no explicit when-to-use / when-not-to-use statement. Nothing tells the agent to prefer this over hgr_get_ai_agent_dashboard or to call hgr_list_channels first for the required ID (the schema covers that, but the description does not reinforce it).

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds an auth-related note about the HGRApi Header channel and ChannelOAuthId being resolved internally, which is useful context beyond the annotations. It does not add other behavioral details such as rate limits or output characteristics, but the output schema and annotations reduce the burden.

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

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

The description is two sentences and front-loads the main operation before the auth note. There is no filler or redundant explanation. The second sentence is somewhat awkwardly phrased, which slightly reduces clarity but not enough to call it 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?

This is a read-only dashboard metrics tool with an output schema, rich annotations, and a fully documented single parameter. The description provides the essential scope — one visible store — and an auth note, so an agent has enough to call it correctly. It could be stronger with explicit sibling routing, but it is complete for the tool's complexity.

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

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

There is only one parameter, and the schema description coverage is 100%; the schema explains that channelOAuthId comes from hgr_list_channels for the selected visible store. The description adds little beyond repeating the ChannelOAuthId concept, and the phrase 'resolved internally' is ambiguous for a parameter that the schema marks as required. With the schema doing the heavy lifting, the baseline score of 3 is appropriate.

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

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

The description states a clear verb and resource: it reads AI Agent dashboard and maturity metrics. It also scopes the operation to one visible store, making the purpose understandable without opening the schema. It does not explicitly differentiate itself from nearby AI Agent tools such as hgr_get_ai_agent_configuration, which keeps it short of a 5.

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

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

Usage is implied by 'reads AI Agent dashboard and maturity metrics for one visible store' — an agent can infer it should call this when dashboard or maturity data is needed. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative for related AI Agent configuration or task data. That places it at implied usage rather than explicit routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds two useful behavioral facts the annotations do not: the endpoint is fixed rather than a generic caller, and channel/ChannelOAuthId is resolved internally as a header channel. It adds nothing about what is returned or about paging/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?

The text is boilerplate-heavy template filler ('Dedicated HGRApi tool for...', 'Purpose:', 'Use when:', 'Search terms: ai gettasks') that repeats the same idea three times. The one genuinely useful constraint (not a generic endpoint caller) is buried mid-paragraph rather than front-loaded.

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

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

With an output schema present, return values need not be explained, but the description still has a required-parameter contradiction and says nothing about whether tasks are filtered, paged, or scoped to the channel. For a tool whose only argument is a channel credential, that leaves real ambiguity.

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

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

Schema coverage is 100% and the single parameter is well described there, so the baseline would be 3. But the description actively misleads by saying 'Input: No explicit input parameters required' when channelOAuthId is a required parameter, which could cause the agent to omit it.

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

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

The description names the verb+resource (GET api/AI/GetTasks) and places it in the 'AI optimization task management' domain, and it explicitly says it is not a generic endpoint caller. However, 'Provides the GET get tasks operation' largely restates the tool name, and it never distinguishes this tool from nearby siblings such as hgr_post_ai_gettaskresult or hgr_post_ai_createtask, leaving the agent to guess which AI-task tool to pick.

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 'Use when' clause is circular: 'Use it when a client needs to run the get tasks operation.' That gives no condition, no prerequisite, and no alternative tool to consider, so the agent gets no real routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description carries a lighter burden. It adds an auth-setup note about the HGRApi Header channel, but that note is cryptic — "ChannelOAuthId resolved internally" sits oddly against a required channelOAuthId parameter — and nothing is said about what happens when the store is not visible to the caller.

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

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

Two short sentences, front-loaded with the purpose before the auth caveat; nothing is padded. The second sentence's slash-delimited phrasing ("HGRApi Header channel / ChannelOAuthId") is terse to the point of ambiguity, costing a point.

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

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

An output schema exists, so return values need not be explained, and both parameters are described. Still, for an open-world data-read tool the description leaves gaps an agent would want: whether filters are store-specific or global, what the body's Status values mean, and how visibility failures surface.

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

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

Schema coverage is 100%, so both parameters are already documented, including the hgr_list_channels provenance of channelOAuthId. The description adds only the "visible store" scoping notion and no detail on the body's Status values or expected shape, so baseline 3 applies.

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

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

The description names a specific verb and resource — "Reads AI Publisher filters/automation configuration" — with scope limited to "one visible store." That is clearly separable from siblings like change_ai_publisher_status, update_ai_publisher_optimization, and get_ai_agent_configuration, though none are named explicitly.

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

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

The phrase "for one visible store" implies the context in which the tool applies and hints that a channel scope must be selected first, but there is no explicit when-to-use clause, no exclusions, and no pointer to a sibling for adjacent cases (e.g. history vs. optimization settings).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds a useful auth note about the HGRApi Header channel, but the clause 'ChannelOAuthId resolved internally' sits awkwardly against a schema that marks channelOAuthId as a required caller-supplied parameter, creating mild confusion about who supplies it.

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

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

Two short sentences with the operation and scope front-loaded; there is no filler. The second sentence is the weakest part, since its auth clause is partially redundant with the schema and partially inconsistent with 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?

An output schema exists and annotations cover the read-only profile, so return values and safety need no prose. Still, the description never says what the history records represent or how far back they go, and the 'resolved internally' note muddies rather than clarifies parameter sourcing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (including that ChannelOAuthId comes from hgr_list_channels). The description adds no meaning beyond that baseline and does not clarify what the 'body' request payload should contain.

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 ('Reads AI Publisher history') plus scope ('for one visible store'), which separates it from siblings like hgr_get_ai_publisher_filters, hgr_change_ai_publisher_status, and hgr_update_ai_publisher_optimization. What 'history' actually contains is left unexplained, keeping it 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?

No when-to-use guidance, no prerequisites, and no naming of the adjacent AI Publisher tools an agent might confuse this with (filters, status change, optimization update). The phrase 'for one visible store' hints at a preconditions step but does not spell one out.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds some context that the channel/ChannelOAuthId is resolved internally and that this is a fixed endpoint rather than a generic caller, but its output statement ('returns the result or applies the effect') is a meaningless catch-all.

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 padded with template boilerplate ('Search terms:', 'not a generic endpoint caller', 'Requires HGRApi Header channel / ChannelOAuthId resolved internally') and repeats 'being watched operation' multiple times. It is not front-loaded with the distinguishing information an agent needs.

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

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

With an output schema present, return values need not be explained, and the single fully-documented parameter is covered. What remains missing is a real explanation of how this dataset differs from the two adjacent analytics siblings, leaving the agent's selection decision under-informed.

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

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

The single parameter is fully described in the schema (100% coverage), including its source from hgr_list_channels. The description mentions the channel input but adds no syntax or format details beyond the schema, so the 3 baseline applies.

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

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

It states a specific verb and resource (GET the being-watched analytics for current-channel watcher analytics), which is better than a bare tautology. However, it never distinguishes this from the very similarly named siblings hgr_get_analytics_getwatchers and hgr_get_analytics_productsnotbeingwatched, leaving the actual semantic difference ambiguous.

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

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

The only guidance is circular: 'Use it when a client needs to run the being watched operation for current-channel watcher analytics' – it restates the purpose rather than giving when-to-use/when-not conditions. No mention of when to prefer getwatchers or productsnotbeingwatched.

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 that the channel/ChannelOAuthId is resolved internally and that it is a fixed, non-generic endpoint, but it says nothing about return content, time window semantics of 'minutes', or pagination. The 'applies the effect' phrasing is boilerplate, not insight.

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 repeats 'get watchers operation' three times across purpose, usage and output, and pads with boilerplate ('dedicated HGRApi tool', 'explicit tool with a fixed endpoint', 'Search terms'). It is front-loaded but bloated with low-value scaffolding.

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

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

With an output schema present and full param coverage, the mechanical call path is complete. However, the key semantics an agent needs — what 'watchers' actually measures and how 'minutes' scopes the result — are never explained, leaving a gap for a tool whose value is in interpreting the analytics.

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

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

Schema coverage is 100% and the schema already documents both params, including channelOAuthId's provenance from hgr_list_channels. The description only echoes 'minutes: int?' and that channel is a header, adding little. Baseline 3 is appropriate given the schema does the work.

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

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

It states a specific verb+resource (GET watchers) and adds that it operates over 'current-channel watcher analytics', but the core phrasing 'Provides the GET get watchers operation' largely restates the name, and it never names the nearest siblings (hgr_get_analytics_beingwatched, hgr_get_analytics_productsnotbeingwatched) to show how it differs.

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 'Use when' clause is circular: 'Use it when a client needs to run the get watchers operation for current-channel watcher analytics' just re-describes the tool. No exclusions and no routing to the adjacent analytics siblings that clearly compete for the same intent.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so safety behavior is covered. The description adds that this is a fixed endpoint rather than a generic caller and that the Header channel/ChannelOAuthId is resolved internally, but it does not explain data freshness, scope semantics, or rate/limit behavior.

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

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

The description is structured with labels and front-loads the endpoint purpose, but it contains repetitive boilerplate such as 'explicit tool with a fixed endpoint' and an 'Output' sentence that says only 'returns the result or applies the effect.' It is adequate but not tight.

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

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

For a one-parameter read-only analytics endpoint, the description plus schema, annotations, and output schema give enough to call the tool correctly. However, it leaves out the practical distinction from sibling watcher-analytics tools and does not clarify what 'not being watched' means operationally.

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

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

Schema description coverage is 100%, and the single required parameter channelOAuthId is already documented in the schema as coming from hgr_list_channels. The description's 'Input: Header channel: current ChannelOAuthId' adds little beyond that, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: getting products not being watched in current-channel watcher analytics. It is clearer than a bare endpoint name, but it does not distinguish this tool from close siblings such as hgr_get_analytics_beingwatched or hgr_get_analytics_getwatchers.

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 'Use when' sentence only restates the tool's name and purpose: 'when a client needs to run the products not being watched operation.' It gives no meaningful selection criteria, exclusions, or alternatives among the analytics siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered by structured data. The description adds only the qualifier that the profile is the one 'visible to the web app', which hints at scoping/visibility but does not explain what that means in practice.

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

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

One short sentence that is front-loaded with the action and resource. The trailing clause 'visible to the web app' is slightly vague but not padding that obscures the core statement.

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 inputs, an output schema present, and annotations covering safety and openness, the description does not need to explain return values. What remains missing is a note on whose profile is returned when multiple integrations exist, but for a zero-arg identity read the definition is sufficient to invoke 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 tool takes zero parameters, which is the baseline-4 case. Nothing extra is needed, and the description does not waste words inventing parameter guidance.

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?

A concrete verb ('Reads') plus specific resource ('authenticated HGR user profile') makes the purpose immediately clear. It does not, however, distinguish this from related siblings such as hgr_get_user_gettokenbalance or hgr_get_user_gettokenhistory, which also operate on the current user.

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

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

There is no statement of when to call this versus the other user/account GET tools in a 150+ tool sibling list. The agent is left to infer that this is the identity/profile lookup, with no exclusions or alternatives 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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only 'from WAPI' and 'current' — a hint that this is a live external fetch — but says nothing about rate limits, failure modes, or what 'fees' means in this domain.

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

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

A single front-loaded sentence with no wasted words. It is arguably too terse rather than too long, but structurally clean.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. However, for a domain-specific concept like 'auto-ordering fees' the description gives no grounding — units, currency, or what the fee applies to — leaving an agent to guess at the meaning of 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, though it also doesn't clarify that no arguments are needed.

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

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

States a specific verb and resource: 'Reads current auto-ordering fees'. This is distinguishable from the closest sibling hgr_get_autoordering_configuration, which returns configuration rather than fees, though the description doesn't call that distinction out explicitly.

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

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

There is no indication of when to call this versus hgr_get_autoordering_configuration or hgr_get_dashboard_taskpendingautoorder2, and no prerequisites (e.g., whether auto-ordering must be configured first). The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the description's job is lighter. It still adds real value: channel auth is resolved from the HGRApi header internally (no extra credential plumbing), and secret fields are redacted before return, which tells the agent to expect masked values rather than data loss.

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

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

Three tight sentences, front-loaded with what it does, followed by auth handling and redaction behavior. No filler or redundancy.

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

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

For a single-parameter read tool with an output schema and full annotation coverage, nothing material is missing: the agent knows scope, auth handling, and that secrets come back masked. Return-value details are correctly left to the output schema.

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

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

Schema description coverage is 100% and the single parameter is fully documented in-schema, including the hgr_list_channels sourcing, so baseline 3 applies. The description adds no format or constraint detail beyond that.

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 ("Reads auto-ordering configuration") plus scope (one visible store/channel) and origin (WAPI). The read framing clearly separates it from the sibling write operations hgr_save_autoordering_configuration and hgr_remove_autoordering_configuration.

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?

"for one visible store/channel" implies this is a per-channel lookup, and the schema points to hgr_list_channels as the source of the ID, but the description itself never states when to use this versus the save/remove siblings or any prerequisites. Usage is inferable rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context that this is a fixed-endpoint tool rather than a generic caller, and mentions the HGRApi header channel, but the claim that ChannelOAuthId is "resolved internally" conflicts with the schema, which marks it as 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?

The text is bloated with template boilerplate: "Dedicated HGRApi tool for GET ...", "This is an explicit tool with a fixed endpoint; it is not a generic endpoint caller", "functional documentation:", and duplicative Purpose/Use-when/Search-terms blocks. The one differentiating fact (fixed endpoint) is buried mid-paragraph.

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

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

An output schema exists, so return values needn't be described, and annotations cover safety. But for a single-param tool the description still leaves the core question unanswered: what a "product source" is and what this retrieval is for. The parameter mismatch with the schema further undermines completeness.

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

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

Schema coverage is 100% and the single parameter is well documented there, which would normally establish a 3 baseline. But the description states "Input: id: int", which does not match the schema's required channelOAuthId property, actively misleading an agent about what to supply.

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?

"Provides the GET get product source operation in catalog/source candidate discovery or publication" essentially restates the tool name. The vague phrase "catalog/source candidate discovery or publication" doesn't tell the agent what data actually comes back, nor does it distinguish this from siblings like hgr_get_sources, hgr_get_sources_get, or hgr_get_source_configuration.

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?

"Use it when a client needs to run the get product source operation" is circular and gives no trigger, no prerequisite, and no alternative tool. With a large sibling set of source/catalog GET tools, an agent has no basis for choosing this one over the others.

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 still adds substantive context: the header channel identifies the selected store, no request body is sent, ListingStatus.Status is a bitmask that can combine flags, and Url identifies new publications before ProductSourceId resolution. These are real consumption-relevant details an agent would not 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?

The labeled Purpose/Use when/Input/Output structure is front-loaded and scannable, but the opening two sentences ('Dedicated HGRApi tool for GET ... it is not a generic endpoint caller') and the trailing 'Search terms:' line are meta-boilerplate that earns no place in the description. Useful content is interleaved with filler.

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

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

An output schema exists, so return-value documentation is not strictly required, and the description nonetheless sketches the shape (job status with EnumValues, listing status/error, bitmask semantics). With a single fully documented parameter and clear read-only semantics, 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?

There is only one parameter and schema coverage is already 100%, with the schema itself explaining that channelOAuthId comes from hgr_list_channels. The description restates that the header channel identifies the selected store, which is mild reinforcement. The note that ChannelOAuthId is 'resolved internally' slightly muddies the fact that it must be supplied, so this is baseline rather than value-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?

The description states a specific outcome: it returns recent catalog publication jobs and their listing results, and explicitly excludes product discovery. That distinguishes it from product-oriented siblings such as hgr_post_catalog_getproducts. The opening is slightly diluted by generic boilerplate about being a 'dedicated HGRApi tool' for a fixed endpoint, but the Purpose line carries the meaning.

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

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

It gives an explicit 'Use when' clause (inspect recorded publication status or errors) and an explicit exclusion (not to discover supplier products). The alternative is characterized by task rather than named as a specific sibling, so an agent must map the task description itself, but the 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 already declare this as a safe, idempotent read. The description adds some useful operational context about the HGRApi Header channel and internal ChannelOAuthId resolution, but the phrasing is compressed and does not clarify error behavior or other runtime characteristics.

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 definition is only two sentences and front-loads the core read operation. The second sentence is dense and slightly cryptic, but there is no obvious 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 read tool with rich annotations, a fully documented single parameter, and an output schema, the description is close to sufficient. However, it remains ambiguous relative to the many other configuration-getter siblings, so an agent lacks enough routing detail for confident selection.

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

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

Schema description coverage is 100%, and the only parameter is already documented in the schema as the ChannelOAuthId returned by hgr_list_channels. The description references ChannelOAuthId but does not add format or selection details beyond what the schema provides.

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

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

The description names a specific verb and resource: it reads store/channel configuration for one visible store. That is clear enough for an agent to know what it returns, though it does not distinguish this tool from nearby configuration getters such as hgr_get_source_configuration or hgr_get_channellisting_getsettings.

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 states the tool reads configuration for one visible store, but gives no explicit when-to-use guidance and does not name alternatives or exclusions. With many sibling configuration-read tools, an agent still has to infer when this one is appropriate.

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, openWorld, so the safety profile is covered. The description adds a modest piece of context — a channel/ChannelOAuthId header must be resolved and is handled internally — which is genuinely useful beyond the annotations, but the rest is boilerplate restatement.

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 text is bloated with auto-generated filler ('Dedicated HGRApi tool for...', 'This is an explicit tool with a fixed endpoint; it is not a generic endpoint caller') and repeats the channel/ChannelOAuthId requirement twice. Front-loading is poor: the actual operation is buried in boilerplate.

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?

Parameters are fully covered by the schema and an output schema exists, so return values needn't be described. But the description's core purpose — what category information is returned and in what context it's used — remains unexplained, leaving an agent with gaps for a discovery/read call among many category siblings.

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

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

Schema description coverage is 100%, so the schema already documents both 'id' and 'channelOAuthId'. The description repeats '[FromQuery] id: string' and the channel header without adding format, valid-value, or lookup detail beyond the schema, so baseline 3 applies.

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

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

The description mostly restates the tool name/endpoint ('GET get category info operation'), which is tautological. It never explains what 'category info' actually contains (category tree? marketplace categories for a channel listing?) or how it differs from close siblings like hgr_get_channellisting_getcustomcategories or hgr_post_channellisting_getcategoriesbytext.

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?

'Use it when a client needs to run the get category info operation' is circular and gives no real when-to-use condition, no exclusions, and no alternative among the many category-related siblings. The only useful fragment is that it belongs to published product creation/optimization, which is too broad to route reliably.

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 state readOnly, idempotent, openWorld and non-destructive, so safety is covered. The only description-added behavior is that the tool is 'not a generic endpoint caller' and that the channel header is 'resolved internally' – marginal context. Nothing about what the category list contains, whether it is channel-specific, or how to interpret the output.

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 padded with boilerplate ('Dedicated HGRApi tool...', 'Search terms:', 'HGRApi functional documentation:') that repeats the tool name and adds no decision-relevant information. The useful content (one input, one output) is buried rather than front-loaded.

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

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

An output schema exists and annotations cover safety, so those needn't be explained. However, for a read tool whose value depends on knowing what custom categories are and when they are needed in a listing workflow, the description leaves the core semantic question unanswered. It also fails to route the agent among the several nearby category-related siblings.

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

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

Schema coverage is 100% and the single channelOAuthId parameter is well documented in the schema (returned by hgr_list_channels for the selected visible store). The description only repeats that the header channel/ChannelOAuthId is resolved internally, adding little beyond the schema. Baseline 3 applies.

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

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

The description restates the endpoint name ('GET api/ChannelListing/getCustomCategories') and the tool name without explaining what a 'custom category' is or what the result represents. 'Provides the GET get custom categories operation in published product creation and optimization' is essentially tautological. It gives no way to distinguish this from siblings like hgr_get_channellisting_getcategoryinfo or hgr_post_channellisting_getsuggestedcategories.

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 'Use when' clause is circular: 'Use it when a client needs to run the get custom categories operation.' No alternatives are named, no exclusions, no prerequisites beyond a passing mention of needing ChannelOAuthId.

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, so the safety profile is covered. The description does add one genuinely useful behavioral fact: the HGRApi Header channel / ChannelOAuthId is resolved internally, and it clarifies this is a fixed-endpoint call rather than a generic proxy. Beyond that, "Returns the result or applies the effect" is vacuous, and it says nothing about rate limits or error behavior.

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

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

The endpoint is front-loaded, but the body is padded with boilerplate: a redundant restatement that it is "not a generic endpoint caller," duplicated Purpose/Use-When sentences that say the same thing, and a trailing "Search terms:" line that just repeats the tool name. Very little of the text earns its place.

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

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

An output schema and full annotations mean the description needn't explain returns or safety, but for a three-required-parameter tool it still leaves the core question unanswered: what settings are retrieved and why do sourceId and sourcePrice matter together. Given ~130 sibling tools in this namespace, the missing differentiation is a real gap.

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

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

Schema description coverage is 100%, so the three parameters are already documented in the schema, and the description adds no meaning beyond repackaging them as "[FromQuery] sourceId: int. [FromQuery] sourcePrice: decimal." It does not explain the relationship between sourcePrice and the settings being fetched, which is the one piece of semantics an agent would actually want. Baseline 3 applies.

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

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

"Provides the GET get settings operation" and "Get Channellisting Getsettings" are the same statement repeated; the only concrete content is the raw endpoint path. An agent cannot tell what these "settings" are (pricing? channel config? source settings?) nor how this differs from siblings such as hgr_get_source_configuration, hgr_get_channel_configuration, or hgr_save_channel_setting. It technically names a verb and resource, but only by restating the name.

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

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

The "Use when" clause is circular: use it "when a client needs to run the get settings operation." There is no alternative named, no precondition stated, and no exclusion such as when to prefer hgr_get_channellisting_getcategoryinfo or the configuration-getter siblings. Nominal guidance exists but carries no decision value.

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, and destructiveHint=false, lowering the burden. The description adds some useful context: fixed non-generic endpoint, the channel header being supplied as ChannelOAuthId, and that it is resolved internally. It does not clarify what the returned value means or what happens when the brand is not found.

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

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

Two sentences with zero waste, and the exclusion from generic endpoint callers is front-loaded ahead of the alternative routing.

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?

Two sentences with zero waste, and the exclusion from generic endpoint callers is front-loaded ahead of the alternative routing.

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

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

Schema coverage is 100%, so both parameters are already documented, including channelOAuthId pointing back to hgr_list_channels. The description only echoes '[FromQuery] brand: string' and 'Header channel: current ChannelOAuthId', adding format detail (query vs. header) but no new semantic 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?

The description restates the tool name and endpoint path ('GET is brand in ve ro list operation') without explaining what the operation actually determines, e.g., whether a brand appears on a VeRO/IP-restriction list. It never distinguishes this tool from siblings like hgr_get_channellisting_getsettings or hgr_get_channellisting_getcategoryinfo beyond the verbatim endpoint name.

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

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

'Use when: Use it when a client needs to run the is brand in ve ro list operation' is circular — it repeats the tool name rather than describing a decision scenario. No alternatives, prerequisites, or when-not conditions are given, so an agent must guess between this and the other ChannelListing GET tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the description correctly spends its words elsewhere: it clarifies that values are computed/effective rather than raw, warns that boolean flags do not toggle supplier state, and states the auth requirement (HGRApi header channel via the internally resolved ChannelOAuthId). That is real added context rather than annotation repetition.

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 definition is front-loaded in the first sentence, and each following sentence adds a distinct guardrail (data type, boolean caveat, auth). It is dense but mostly earns its length; the auth sentence is the weakest and could be folded into the schema note 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 an output schema present and annotations covering the safety profile, the remaining burden is to say what the data represents and what it is not, which the description does well. The only gap is the absence of any routing signal toward the similar source-configuration siblings.

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

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

Schema coverage is 100% and the parameter description already tells the agent to obtain the value from hgr_list_channels, so the baseline of 3 applies. The description's 'ChannelOAuthId resolved internally' slightly muddies things, since the schema marks the parameter as required and caller-supplied; a agent could plausibly read these as conflicting.

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 ('Reads effective supplier settings') and explains the 'computed' semantics: store defaults merged with supplier overrides. It also scopes the data negatively ('not supplier availability or listing usage data'). However it never names or contrasts with the close sibling hgr_get_source_configuration, so the agent must infer why both exist.

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 useful exclusion guidance ('this is settings data, not supplier availability or listing usage data') and warns that boolean monitoring settings are informational. But it offers no positive trigger for when to call this instead of hgr_get_source_configuration or hgr_get_sources, leaving the selection decision to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world, so the safety profile is covered elsewhere. The description adds only the boilerplate claim that it is a fixed endpoint rather than a generic caller; the output sentence ("Returns the result or applies the effect") is meaningless for a read operation and no rate limits, auth needs, or data shape are given.

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 text is padded with duplicated boilerplate ("explicit tool with a fixed endpoint; it is not a generic endpoint caller"), a redundant route path, and a trailing "Search terms" line that repeats the name. The useful content — input types — is buried mid-paragraph rather than front-loaded.

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

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

With annotations and an output schema present, the bar is moderate, and the description covers the route and parameter types. Still missing are the permissible values of the ePeriod enum and any hint about what the statistics payload contains or how date ranges are interpreted, which are the details an agent would most need.

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 nominally 100%, but the schema descriptions are empty boilerplate ("HGRApi route parameter period"). The description's Input section meaningfully upgrades this by revealing that period is of type ePeriod (an enum, though values are not listed) and that from/to are nullable DateTimes bound from the route — information the schema does not convey.

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

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

The description does state a verb and resource ("get affiliate statistics" for dashboard data) and identifies the fixed route, but the phrasing is largely a restatement of the generated name. It never distinguishes the tool from close siblings such as hgr_get_affiliate_dashboard or hgr_get_affiliate_dashboard_monthly, so an agent cannot choose between them from this text alone.

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

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

"Use it when: Use it when a client needs to run the get affiliate statistics operation for dashboard data" is circular and adds no decision criteria. No alternatives, exclusions, or preconditions are named despite several affiliated dashboard tools existing in the sibling list.

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

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

Read-only, idempotent and non-destructive behavior is already declared in the annotations, so the description only needs to add context. It adds the store scope (all_user_stores) and confirms the call takes no concrete listing IDs, which helps set expectations about the result set. It does not discuss pagination or result size, a minor gap for a list operation.

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

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

The labeled structure (Purpose / Use when / Input / Output) is front-loaded and easy to scan. However, gateway boilerplate ('explicit tool with a fixed endpoint; it is not a generic endpoint caller') and the trailing 'Search terms: dashboard getlistingservices' add little value. The useful content would fit in fewer words.

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

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

Annotations cover the safety profile, and an output schema exists, so the description only needs to frame purpose, scope and usage. It does all three. The one omission is how large the returned service list can get, which is modest given the output schema.

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

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

The tool takes zero parameters, so the schema by itself already covers the input contract. The description reinforces this by stating that no input is required and that listing IDs are not used, which prevents an agent from wrongly supplying identifiers. It adds useful meaning beyond an 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?

The description states a specific verb and resource: lists the publication services purchased by the user, via GET api/Dashboard/GetListingServices. That separates it from sibling dashboard reads such as hgr_get_dashboard_getlistingsummary or hgr_get_dashboard_getpendingstatistics. It stops short of naming those siblings as alternatives, so it falls below the top score.

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 'Use when' line gives a concrete trigger: show pending or purchased We List For You orders/services. That is a clear positive usage condition. The description never states when not to use it, and it does not point to an alternative dashboard tool for related metrics.

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, open-world, so the safety profile is covered. The description adds scope (current_store) and a note that the channel is resolved from the ChannelOAuthId, but it also says the header channel is 'resolved internally' while the schema makes channelOAuthId a required input, which muddies rather than clarifies runtime behavior.

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

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

The purpose and usage are front-loaded after several sentences of boilerplate ('Dedicated HGRApi tool for GET api/...', 'This is an explicit tool with a fixed endpoint'). A redundant 'Search terms: dashboard getlistingsummary' line repeats the tool name and earns little.

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 one required parameter, full schema documentation, an output schema, and safety annotations, the description supplies the remaining context an agent needs: data scope, when to use it, and what kind of aggregates it returns. Only the channel-resolution ambiguity slightly weakens completeness.

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

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

Schema coverage is 100% and the parameter description already explains that channelOAuthId comes from hgr_list_channels. The description only restates that the header channel is the current ChannelOAuthId and adds that concrete listing ids are not used — marginal added meaning, so the baseline 3 applies.

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

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

The description states a specific verb+resource: returns an aggregate summary of published products, recent products, and average price for the current channel. It also names the domain/entity/operation (listings, listing_summary, aggregate), which separates it from list-oriented siblings like hgr_get_active_listings. The useful content is somewhat buried under endpoint boilerplate, which keeps it from 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?

It gives an explicit 'Use when' clause (dashboard views or aggregate metrics for the selected channel) and an exclusion ('Does not use concrete listing ids'), which steers the agent away from id-specific tools. It does not name a concrete alternative sibling, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered elsewhere. The description adds nothing beyond that — no note on what the endpoint actually returns, whether results are cached, or what openWorld access to servers implies. The only added statement is that it takes no input, which the schema already shows.

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?

Roughly half the text is boilerplate: the "explicit tool with a fixed endpoint; not a generic endpoint caller" sentence and the search-terms tail add no information. The substantive content could be one sentence.

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

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

With an output schema present and no parameters, the definition is technically callable, but it leaves the domain meaning of "no API servers" unexplained and provides no hint about result size or shape for an openWorld read.

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

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

Zero parameters, so the baseline is 4; the description correctly states "No explicit input parameters required," which is consistent with the empty schema. Nothing further is needed.

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

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

It names a specific operation (GET api/Dashboard/GetNoApiServers) but only restates the endpoint path; it never explains what a "no API server" actually is or what the dashboard returns. An agent can match it by name but cannot tell what it does in domain terms, nor distinguish it from hgr_get_noapi_servers or hgr_update_noapi_servers.

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 "Use when" line is circular — use it when a client needs to run this operation — giving no real trigger condition. There is no mention of when to prefer hgr_get_noapi_servers (the near-identical sibling) or any exclusion.

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 non-destructive, so the safety profile is covered. Beyond that the description only says it "returns the result or applies the effect," which is generic filler, and the claim that channelOAuthId is "resolved internally" is at odds with the required-parameter schema, potentially misleading an agent about auth. No disclosure of what data is returned, freshness, or cost.

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?

Boilerplate dominates: the "explicit tool with a fixed endpoint; it is not a generic endpoint caller" sentence conveys little, and the auth note is repeated at both the start and the end. The single genuinely useful clause (search terms) is buried after redundant scaffolding.

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

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

An output schema exists so return values need not be described, but the description still fails to say what the count represents, what unit it is in, or when it beats the many neighboring dashboard endpoints. For a one-parameter read in a dense sibling set, this leaves the agent unable to choose it confidently.

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

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

Schema description coverage is 100% and the single parameter's schema text ("returned by hgr_list_channels for the selected visible store") is strictly more informative than the description's "Header channel: current ChannelOAuthId." Baseline 3 applies since the schema does the work.

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 restates the tool name: "Provides the GET get optimized count operation in dashboard data." It identifies the HTTP verb and endpoint but never explains what an "optimized count" actually counts, which is the one thing an agent cannot infer from the name. Sibling tools like hgr_get_dashboard_getlistingsummary or hgr_get_dashboard_getpendingstatistics similarly get no differentiation.

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

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

"Use when: Use it when a client needs to run the get optimized count operation for dashboard data" is circular – it tells the agent to use the tool when it needs the tool. No exclusions, prerequisites, or comparison to the other 15+ hgr_get_dashboard_* siblings are offered. The only concrete guidance is the passive note that channelOAuthId comes from hgr_list_channels, which duplicates the schema.

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, and non-destructive behavior, so the description does not need to carry the full safety burden. It adds that the endpoint is fixed and requires a ChannelOAuthId header, but otherwise uses generic language like 'returns the result or applies the effect' and omits rate limits, pagination, or data-scope details.

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 endpoint is front-loaded and the description is organized into purpose/use/input/output sections. However, it contains auto-documentation boilerplate, repeated phrases about being dedicated/explicit/not generic, and search terms that add little for an agent.

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 one required parameter at full schema coverage, rich annotations, and an output schema, the description contains enough to invoke the tool. It is still incomplete for selection because it does not explain what pending statistics are or how this tool should be chosen over the other dashboard endpoints.

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

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

Schema description coverage is 100%, so the schema already fully documents the sole channelOAuthId parameter. The description repeats that it is a header channel parameter but does not add meaningful semantics beyond the schema.

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

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

The description names the exact GET endpoint and says it returns dashboard pending statistics, but the purpose line mostly restates the tool name and endpoint. It does not explain what 'pending statistics' actually contain or differentiate this from the many other dashboard statistics 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 'Use when' section merely says to use it when a client needs to run the operation, which is tautological. It gives no alternatives, prerequisites beyond the header note, or exclusions versus sibling dashboard tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered elsewhere. The description adds essentially nothing behavioral beyond confirming 'No explicit input parameters required' — it does not say what an upcoming webinar record is, whether results are scoped to the authenticated user, or how many entries come back (despite an output schema existing). No contradiction with annotations.

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

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

The text is padded with template boilerplate: the purpose is stated three times (dedicated tool line, 'Purpose:' line, and a repeated 'Output: Returns the result or applies the effect of the ... operation'), plus a redundant 'Search terms' tail. It is front-loaded but wastes most of its length on repetition rather than substance.

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 zero parameters, an output schema, and rich annotations, the definitional bar is low and what exists is technically sufficient to invoke the tool correctly. However, it never explains what data an 'upcoming webinar' response actually contains or how it relates to the other dashboard endpoints, so the agent must guess at its relevance.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly confirms 'No explicit input parameters required', consistent with the empty schema and additionalProperties=false.

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 restates the tool name almost verbatim: 'Provides the GET get upcoming webinar operation in dashboard data' adds no information beyond the identifier. The only genuine content is the disclaimer that it is 'not a generic endpoint caller', but nothing distinguishes it from sibling dashboard getters such as hgr_get_dashboard_getlistingsummary or hgr_get_dashboard_getpendingstatistics.

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?

'Use when: Use it when a client needs to run the get upcoming webinar operation for dashboard data' is circular — the condition is the operation itself. No alternatives, prerequisites, or when-not guidance are given, so an agent has no basis to choose this over any other hgr_get_dashboard_* sibling.

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, destructiveHint=false, and openWorldHint=true. The description adds no behavioral context such as authentication needs, rate limits, or side effects, and its output statement 'Returns the result or applies the effect' is too vague to be useful.

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 has labeled sections, but it repeats boilerplate about being a dedicated tool and includes low-value text such as 'Search terms: dashboard requestcode.' The useful endpoint information is front-loaded, but several sentences do not 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?

An output schema exists, so return values need not be explained in detail. However, the description fails to explain the core 'request code' concept, which is essential for distinguishing this tool from numerous sibling dashboard GET tools.

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

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

With 100% schema description coverage and only one parameter, the schema already documents the id field. The description adds '[FromQuery] id: int' but does not explain what the id represents beyond the type binding, so the baseline score of 3 is appropriate.

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

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

The description largely restates the tool name and endpoint path: 'Provides the GET request code operation in dashboard data.' It never explains what a 'request code' is or what the operation returns, so the purpose remains tautological rather than specific.

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 'Use when' guidance is circular: 'Use it when a client needs to run the request code operation for dashboard data.' It names no alternatives and gives no conditions for choosing this over the many other dashboard-related sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, and the description adds essentially nothing on top — only that the ChannelOAuthId header is "resolved internally" and that output "returns the result or applies the effect," which is vacuous for a read 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?

Boilerplate dominates: "explicit tool with a fixed endpoint," "functional documentation," and a redundant "Search terms" line that repeats the tool name twice. The actual informative content could fit in one sentence, and the purpose is buried rather than front-loaded.

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

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

An output schema exists, so return values need no explanation, but the description still never tells the agent what entity or metric this endpoint returns or under what dashboard context to call it. For a one-parameter read tool that is technically callable, it leaves the semantic decision — which dashboard endpoint to pick — unsupported.

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

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

Schema coverage is 100% and the single parameter's description already explains it is the ChannelOAuthId from hgr_list_channels. The description only echoes that a channel header is required, so baseline 3 applies.

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

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

The description restates the tool name and endpoint ("GET api/Dashboard/TaskPendingAutoOrder2") but never explains what "task pending auto order2" data actually is. Its only distinguishing claim — that it is "not a generic endpoint caller" — differentiates it from a hypothetical generic tool, not from any of the many dashboard siblings it is listed beside.

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 guidance is circular: "Use it when a client needs to run the task pending auto order2 operation for dashboard data." No when-not conditions, no alternatives among the dashboard siblings (e.g. getpendingstatistics, getoptimizedcount), and no prerequisites beyond a header reference.

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 the safety profile is covered. The description adds that this is a fixed endpoint rather than a generic caller and that ChannelOAuthId is resolved internally, which is modest but useful context; it does not describe response shape or pagination.

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 repeats itself with boilerplate such as 'Dedicated HGRApi tool,' 'explicit tool with a fixed endpoint,' and 'not a generic endpoint caller.' The useful information is buried in redundant phrasing rather than front-loaded.

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

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

Output schema and annotations are present, so return format and safety need not be fully repeated. However, the description still leaves the core purpose ambiguous: an agent cannot tell what this dispatch GET actually retrieves, making it insufficient even for a simple one-parameter 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?

With one parameter and 100% schema description coverage, the schema already explains channelOAuthId and its source. The description adds only that the header channel is resolved internally, so it neither compensates for nor significantly extends the schema.

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

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

The description mostly restates the tool name and endpoint ('GET api/Dispatch/Get') and calls it a 'get operation in shipping and dispatch operations.' It never explains what dispatch data is retrieved or how this differs from siblings such as hgr_post_dispatch_getshipmentdetails.

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 'Use when' clause is tautological: 'when a client needs to run the get operation' gives no real selection criteria. No alternatives or when-not conditions are mentioned despite many sibling dispatch tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds genuinely new behavior: authenticated_user scope and the rejection of legacy numeric ids. That is useful context beyond the structured fields, though no rate-limit or error behavior is described.

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 labeled fields (Purpose/Domain/Entity/Operation/Scope/Use when/Input/Output) are front-loaded and scannable, but boilerplate like 'Dedicated HGRApi tool for GET api/...', the 'not a generic endpoint caller' disclaimer, and 'Search terms' pad the definition without adding selectable information.

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

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

For a single-parameter read with an output schema, everything an agent needs is present: trigger condition, id format constraint, scope, and a short note on the returned payload. Nothing material is missing.

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

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

Schema coverage is 100% with one required string, so the schema does most of the work. The description still adds meaningful semantics: the id is a route parameter and must be a visible TCK-* reference rather than a legacy numeric id.

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

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

States a specific verb+resource+scope: reads one authenticated CRM support ticket by visible ticket id, with 'Operation: get_exact' and 'Entity: support_ticket'. This distinguishes it from hgr_list_support_tickets and hgr_get_support_ticket by noting it reads a single ticket by visible reference.

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 'Use when' clause gives a concrete trigger (user asks about an existing ticket and supplies a TCK-* reference), and it explicitly excludes legacy numeric ids. It does not, however, contrast against the similarly named sibling hgr_get_support_ticket, leaving one plausible ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description's only added claim is auth context ("Requires HGRApi Header channel / ChannelOAuthId resolved internally"), but that misleads: the channelOAuthId is a required caller-supplied parameter, not resolved internally. Nothing about scope, volume of DIDs returned, or pagination is disclosed.

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?

Heavy boilerplate: a disclaimer that it is "not a generic endpoint caller," a duplicated Purpose/Use-when/Input/Output block, and a trailing "Search terms" line. The one useful signal (channelOAuthId) is drowned out and is contradicted by the Input line.

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

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

An output schema exists so return values need no prose, and annotations cover safety. But for a single-parameter tool the description should at minimum explain what the DID list is and confirm the required auth parameter; instead it asserts no input is needed, leaving the agent with less accurate information than the schema alone.

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

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

Schema coverage is 100% and the channelOAuthId description already explains it comes from hgr_list_channels, so the schema does the work. The description actively contradicts it by claiming "No explicit input parameters required," which could cause an agent to omit a required argument.

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 restates the tool name ("Provides the GET did list operation") without ever explaining what a "did list" is or what data the caller receives, so the core resource is opaque jargon. It does name the underlying endpoint GET api/Listing/DidList, but that adds no meaning an agent could not infer from the tool name itself.

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?

"Use when: Use it when a client needs to run the did list operation for bulk publication and publication tracking" is circular — it tells the agent to use the tool when it needs to use the tool. No sibling is named (e.g. hgr_get_listings, hgr_get_active_listings, hgr_post_listing_getbulkhistory), and no when-not or prerequisite conditions are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds that the tool is a fixed endpoint and requires a header channel resolved internally, which is useful but minimal. It does not contradict annotations, but it provides limited additional behavioral context.

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

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

The description is unnecessarily verbose and repetitive. It includes boilerplate like 'Dedicated HGRApi tool for GET...' and 'Search terms: listing listingscountperchannel', which do not aid understanding. The core information could be conveyed in one clear sentence.

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

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

Given the presence of an output schema, the description need not detail return values. However, it lacks meaningful usage guidance relative to siblings, and the boilerplate language reduces clarity. It covers basic input and output context adequately but falls short of fully helping an agent select and invoke the tool correctly.

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

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

Schema description coverage is 100%, and the single parameter (channelOAuthId) is fully documented in the schema. The description repeats that the header channel is the current ChannelOAuthId, adding no new meaning or format details. A baseline of 3 is appropriate when the schema does the heavy lifting.

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 specifies the operation (get listings count per channel) and gives context (bulk publication and publication tracking). It distinguishes the tool from a generic endpoint caller. However, it does not differentiate it from similar siblings like hgr_get_listings or hgr_get_active_listings, leaving ambiguity about when this count-only view is preferred.

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 'Use when' section merely restates the purpose ('run the listings count per channel operation for bulk publication and publication tracking') without providing concrete conditions or alternatives. No guidance is given on when to use this tool versus other listing-related tools in the sibling set.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description adds a genuine operational note about HGRApi header channel resolution, but it is cryptic and says nothing about history depth, time range, or pagination -- and the output schema covers return shape.

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

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

Two short sentences with the purpose front-loaded and no filler. The second sentence is compressed to the point of being hard to parse ('HGRApi Header channel / ChannelOAuthId resolved internally'), which slightly undercuts clarity.

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

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

With a full input schema description, an output schema, and annotations covering the safety profile, the definition carries everything needed to invoke it correctly. Only minor gaps remain, such as what time window the price history spans.

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

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

Schema coverage is 100%, so the schema already documents productId, channelOAuthId and variationProductId with clear meanings. The description only reinforces the variation-selection intent and the channel resolution; it adds no format, precedence, or syntax detail beyond the schema.

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

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

States a specific verb and resource ('Reads price history') and scopes it to 'one exact listing variation', which separates it from coarse-grained siblings like hgr_get_listing_stock_history or hgr_get_searchproduct_pricechanges. It stops short of naming an alternative explicitly, but the resource scope is unambiguous.

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

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

The phrase 'one exact listing variation' implies the granularity of use, but there is no explicit when-to-use / when-not-to-use guidance and no named alternative among the many pricing-related siblings (hgr_get_price_warrior, hgr_get_pricing_rules, hgr_update_price_warrior_settings). Usage must be inferred.

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

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

Annotations already establish read-only, idempotent, open-world, non-destructive behavior, so the description does not need to restate safety. It adds useful context about exact-id-only lookup and an HGRApi Header/channelOAuthId prerequisite, though it does not describe edge-case behavior such as missing ids or partial results.

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

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

The definition is front-loaded with the core behavior, followed by targeted exclusions and alternatives. Every sentence contributes to correct tool selection or invocation, with no filler.

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

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

Given rich annotations, full schema coverage, and an output schema, the description covers purpose, exclusions, alternatives, and auth prerequisites well. A minor gap remains around whether at least one of listingIds or primaryIds must be supplied, since only channelOAuthId is required in the schema.

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

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

Schema description coverage is 100%, so the schema already documents listingIds, primaryIds, and channelOAuthId in detail. The description reinforces that identifiers must be concrete and already known, but adds little parameter-level 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 and resource: gets exact listings by concrete HGR listing ids or visible marketplace primary ids. It clearly separates this from bulk/global listing discovery and explicitly names the active, pending, and terminated listings alternatives.

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

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

Provides explicit when-to-use guidance (only when exact ids are already known) and when-not-to-use guidance (discovery, scanning, ranking, filtering, aggregation, and CSV/XML/XLSX/feed exports). It also routes bulk/global queries to named sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value by flagging that the channel is resolved internally and that ChannelOAuthId must come from hgr_list_channels, but the phrasing 'Requires HGRApi Header channel / ChannelOAuthId resolved internally' is ambiguous about whether the caller must supply a header, and nothing is said about history depth or ordering.

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

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

Two short sentences with the scope statement front-loaded and no filler. The second sentence, however, is dense and reads like a compressed internal note rather than clean prose, costing a point.

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

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

An output schema exists so return values need not be described, and annotations cover the safety profile, which keeps the bar modest. Still, for a history-read tool the description never says what the history contains or over what window, and the header/channel sentence is too vague to fully resolve the one required parameter's provenance.

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

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

Schema description coverage is 100% and the schema already explains productId, variationProductId and channelOAuthId, so the baseline applies. The description's phrase 'one exact listing variation' hints that variationProductId identifies the variation, but it adds no format, default, or mutual-exclusion guidance 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 and resource ('Reads stock history') and narrows scope to 'one exact listing variation', which distinguishes it from the listing-level siblings like hgr_get_active_listings or hgr_get_listings. It does not, however, distinguish it from the closest sibling hgr_get_listing_price_history, whose name follows the identical pattern.

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

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

There is no stated condition for when to call this versus alternatives, and the obvious near-alternative (hgr_get_listing_price_history) is never mentioned. The only usage-like content is a prerequisite ('Requires HGRApi Header channel / ChannelOAuthId'), not a when-to-use rule.

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

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

Annotations already declare the operation is read-only, idempotent, non-destructive, and open-world. Beyond that, the description adds useful behavioral context by noting that passwords and secrets are redacted and connection states are translated to human language, though it does not cover auth requirements 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?

Two concise sentences with no wasted language. The core purpose is front-loaded, and the second sentence efficiently adds relevant behavioral detail.

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

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

With zero parameters, rich annotations, and an output schema, the description is complete enough for correct invocation. It states what is read and notes redaction and connection-state translation, adding useful context without needing to explain return values.

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

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

The tool has zero parameters, so the baseline score is 4. There are no parameter semantics for the description to clarify, and the description appropriately focuses on the resource and output behavior.

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

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

The description uses a specific verb ('Reads') and resource ('No-API Server configuration/status'), making the tool's purpose immediately clear. It does not explicitly distinguish itself from close siblings such as hgr_get_dashboard_getnoapiservers or hgr_get_noapi_solution_state, 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?

The description does not state when to use this tool versus alternatives, nor does it provide any prerequisites or exclusions. The only implied usage is reading No-API Server configuration/status, leaving an agent to infer routing from sibling names.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful context ('translates it to human language', header channel resolution) but the phrase 'ChannelOAuthId resolved internally' is confusing given the schema requires the caller to supply it, and nothing is said about failure modes 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?

Two compact sentences with the core purpose front-loaded; no filler. The second sentence's jargon ('HGRApi Header channel') is slightly opaque but does not pad the text.

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

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

An output schema exists, so return values needn't be explained, and annotations cover safety. What is missing is differentiation from the near-identical noapi-servers siblings, which matters in a toolset this large.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema (including its provenance from hgr_list_channels). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Reads No-API Server verification/connection state') scoped to a visible store, plus the extra behavior of translating it to human language. It does not, however, distinguish itself from the very similar siblings hgr_get_noapi_servers and hgr_get_dashboard_getnoapiservers, so an agent must guess which of the three to call.

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

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

Usage is implied ('for a visible store', with channelOAuthId from hgr_list_channels), which gives a reasonable precondition, but there is no explicit statement of when to prefer this over hgr_get_noapi_servers or when not to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds useful behavioral caveats: pending listing ids may be hidden unless HGRWeb shows them, and the required HGRApi channel header is resolved internally. These are helpful but relatively thin additions against the rich annotation set.

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 is front-loaded in the first sentence, and the following sentences add workflow and caveats without much waste. It is slightly dense but appropriately sized for an 8-parameter list tool.

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

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

The tool has an output schema, full parameter coverage, and rich annotations. The description supplies the remaining operational context: store resolution, projection guidance, ID visibility caveat, and auth header behavior. It is largely complete, though it could say more about pagination behavior or the showWeListForYou flag.

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

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

Schema description coverage is 100%, so parameter semantics are already fully documented in the schema. The description reinforces the use of fields/sortBy/sortDirection/limit for projections and answers, but it does not add syntax or meaning beyond what the schema provides.

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 ('Lists pending listings') and scopes it to 'one visible store,' which distinguishes it from active/terminated listing tools. It does not, however, distinguish it from the sibling tool hgr_list_pending_now, which appears to cover a similar surface.

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

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

It gives an explicit prerequisite workflow ('First resolve the store with hgr_list_channels') and says to do ranking/filtering/summarizing through this tool rather than post-processing. It does not state when to prefer this over hgr_list_pending_now or the pending-statistics tools, so the sibling routing is incomplete.

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, so the safety profile is covered. The description adds the auth context ('Requires HGRApi Header channel / ChannelOAuthId resolved internally'), but leaves the interaction between that internal resolution and the required channelOAuthId parameter vague, and says nothing about result scope or pagination (an output schema exists, which partly excuses this).

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

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

Two short sentences, front-loaded with the operation and scope. The second sentence is terse and somewhat jargon-heavy ('HGRApi Header channel'), but no sentence is padding.

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?

A single-parameter read tool with full schema coverage, complete annotations, and an output schema does not need a long description. The description correctly covers purpose, scope, and auth context, which is all an agent needs to invoke it.

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

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

Schema description coverage is 100% and the single parameter is already documented in-schema as coming from hgr_list_channels. The description adds only the 'one visible store' scoping and the internal resolving note, which does not meaningfully extend what the schema already says.

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: 'Reads Price Warrior dashboard/settings for one visible store', which is clearly a read operation against a named subsystem. It does not explicitly differentiate itself from the sibling hgr_update_price_warrior_settings, though the verb 'Reads' does most of the work.

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

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

The only scoping guidance is 'for one visible store', which is a constraint rather than a when-to-use rule. Nothing tells the agent when to call this versus hgr_update_price_warrior_settings or the numerous other dashboard/pricing tools, and no prerequisites or exclusions are stated.

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