Birinchi Shop — CPA partner API

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. The description adds context the annotations do not: the returned payload, including the somewhat sensitive API key scopes and frozen balance, which materially affects how an agent should handle the response.

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 sentence that front-loads the verb and resource and then lists return fields. Every clause carries information; there is no filler.

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

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

With no output schema, the description must carry return-value information, and it enumerates the key fields (name, status, current balance in UZS, frozen balance, minimum withdrawal, API key scopes). For a zero-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly implies the account is implicit from the authenticated partner context rather than identified by input.

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

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

States a specific verb ('Get') and resource ('the partner account') and then enumerates the exact fields returned, so the agent knows precisely what it receives. Against siblings like get_stats, get_order, or get_insights, this is unambiguously the account-level metadata/balance tool.

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 rather than stated: it is the only account-fetching tool among the siblings, so an agent asking about balance or account status will land here naturally. However, there is no explicit guidance such as when to call this versus get_stats or get_insights for balance-related figures.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavior detail beyond that: the full state machine (pending, running, done, failed, cancelled, expired) and the presence of a result message, which matters for polling decisions.

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

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

One sentence, front-loaded with the resource and origin tools, with the state enumeration placed where it is immediately scannable. No filler and no repetition of the title or parameters.

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

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

For a single-parameter read tool with rich annotations and no output schema, the description covers the essential contract: what is returned (a state plus result message) and where the ID comes from. Only edge behavior — unknown/expired IDs, whether polling is expected — is left unstated.

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

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

Schema coverage is 0%, so the schema gives only type and minimum for action_id. The description compensates partially by defining what the ID refers to — the confirmation card returned by the two campaign tools — but says nothing about ID format, validity, or behavior when the ID is stale or from another source.

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 resource (a confirmation card's status) and enumerates the exact outcome states plus the result message. It also names the two tools that produce the action_id (resume_campaign, change_campaign_budget), which separates it cleanly from siblings like get_ads_status or get_stats.

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 clause 'created by resume_campaign or change_campaign_budget' implicitly tells the agent to call this after one of those write operations, which is the primary when-to-use signal. It stops short of explicit exclusions or stating what to do when the ID is unknown, so it is clear but not fully routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description contributes the shape of the response (connected flag, currency, counts by status), which is genuinely useful given no output schema, but adds nothing about failure modes when no ad account is linked.

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

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

One sentence, front-loaded with the primary question (is the account connected) and then the supplementary fields. No filler to remove.

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 and no output schema, the description must carry the return-value burden and does enumerate the fields returned. Slightly terse on edge cases (account not connected, zero campaigns) but adequate for a simple status probe.

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 baseline 4 applies; the description correctly implies the tool is parameterless and scoped to the calling partner, which is consistent with the empty schema.

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

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

Names the verb/resource precisely: connection state of the partner's Meta ad account plus currency and campaign counts by status. That is a concrete, distinct payload from siblings like get_stats or list_campaigns, though the description never explicitly contrasts itself with them.

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

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

Usage is only implied – an agent can infer this is the lightweight connectivity/health check to call before deeper ad queries, but nothing states when to prefer it over list_campaigns or get_insights, nor any prerequisites (e.g. partner must have a linked ad account).

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

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

Annotations already cover readOnly, idempotent, non-destructive, and closed-world, so the safety profile is settled. The description adds meaningful behavioral context beyond that: the data windows ('yesterday', 'last 7 days vs previous week', 'Meta campaigns (7 days)') and recurring 'this morning's brief', which tell the agent about data recency and aggregation scope. It does not discuss latency or response size for this aggregate call, which keeps it at 4.

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

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

One dense sentence, front-loaded with what the tool is before the enumeration of contents. The long comma/slash list is information-rich rather than padded, but the parenthetical recommendation types ('losing_campaign, stock_out, low_sale_offer...') make it harder to scan than a short bulleted framing would.

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

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

With no output schema and no parameters, the description carries the full burden of describing return values, and it does so thoroughly, covering every section and the recommendation categories. What is missing is any notion of the response shape (e.g. nested keys or sections) beyond the comma-separated enumeration, and whether the view is scoped to the authenticated partner.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies the call is parameterless by describing a fixed snapshot rather than any filtering options.

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

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

It clearly identifies the resource as a composite 'partner's personal AI manager view' and enumerates exactly what it contains (yesterday's orders/earnings, 7-day comparisons, promoted offers with sale rate and stock, Meta campaigns, suggested offers, prioritized recommendations, morning brief). This is specific enough to distinguish it as an aggregate dashboard read versus the granular siblings. It stops short of naming which siblings (get_stats, list_campaigns, search_offers) it replaces, so 5 is not warranted.

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 'today's overview' and 'this morning's brief', signaling a morning-check-in / daily-dashboard call. However, there is no explicit when-to-use, when-not-to-use, or statement that this should be preferred over calling get_stats plus list_campaigns individually. The routing decision is left to inference 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 readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds that the response is heavyweight (images, video, all variants) and includes personalized data ('the partner's existing links ... my_links'), which implies an authenticated per-account view, but it says nothing about behavior on an unknown offer_id or result size.

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

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

One sentence, front-loaded with the verb and resource, with the returned payload enumerations earning their space. No filler or restatement of the title.

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

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

There is no output schema, and the description does the right thing by enumerating the returned fields, including nested variants and personalized links. What's missing is how to obtain the offer_id and whether this is the expensive call in a search-then-detail workflow.

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

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

Schema description coverage is 0%, so the schema documents only type integer, minimum 1 and required. The description does not explain what an offer_id is or where to obtain it, though the single obvious identifier keeps this near the baseline rather than a serious gap.

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

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

Specific verb + resource ('Get full details of one offer') followed by an enumeration of exactly what is returned: description, images, video, variants with their own price/payout, and my_links. The emphasis on a single offer with embedded variants and personal links clearly separates it from search_offers and the list_* 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?

Usage is only implied by 'one offer' — an agent can infer this is the detail-fetch counterpart to search_offers, but the description never names that alternative or states the precondition (you need an offer_id, presumably from search_offers). No exclusions or when-not 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, closed-world), so the description's added value is telling the agent what the response body contains — status, call-center and courier notes, expected delivery_date, tracking values. That is genuinely useful since no output schema exists. It does not say what happens for a missing order id, which keeps it below 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?

A single sentence that front-loads the action and packs the return contents without filler; every clause earns its place.

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

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

For a one-parameter read tool with no output schema, the description adequately covers what comes back. The remaining gap is that the sole input parameter is never characterized and error behavior is unstated.

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 one parameter with 0% schema description coverage, and the description never mentions order_id, its required status, or its integer identity format — 'one order' only vaguely implies lookup by identifier. The description does not compensate for the schema gap.

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

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

States a specific verb and resource ('Get one order') and enumerates the returned content (status, operator/courier notes, delivery_date, tracking). The phrase 'one order' implicitly distinguishes it from list_orders, but no sibling is 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?

Usage is only implied by the singular 'one order' versus the sibling list_orders and get_order_sale_chance; there is no explicit statement of when to pick this over those alternatives or any prerequisite.

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 read-only, idempotent, non-destructive behavior in a closed-world context. The description adds useful behavioral context by explaining that the result is an estimate with specific contributing factors, including network-wide customer history, duplicates, and rejected leads.

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

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

The description is a single front-loaded sentence that states the estimate, its range, and the factors behind it. Every clause earns its place and there is no redundant 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-only tool with one required parameter and no output schema, the description sufficiently explains the return concept: a 0-100% estimate plus contributing factors. The main omission is any clarification of the order_id parameter, but the overall calling context is adequate.

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

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

Schema description coverage is 0% for the sole order_id parameter, so the description must compensate. It only implies that one order is evaluated, without defining order_id format, constraints, or how the identifier is interpreted.

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 ('Estimate') and resource ('that one order will be delivered'), making clear it returns a predictive probability rather than raw order data. It also distinguishes itself from retrieval siblings like get_order by naming the prediction output and contributing factors.

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 case is implied: estimate delivery probability for a single order. However, the description gives no explicit guidance on when to choose this over get_order, get_stats, or other siblings, and no when-not conditions are stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context the schema does not: the default date window of 30 days and the fact that results are aggregated/grouped rather than raw records. It does not say anything about result size, pagination or what happens when both filters and grouping are supplied.

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

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

Two sentences, front-loaded with the metric inventory and the grouping dimension, and the default range tacked on last where it belongs. The measure list is dense but every item is informative; no filler prose.

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 five undocumented parameters, no output schema, and one enum, the description should do more: it leaves the date range semantics and the link_id/offer_id filters unexplained and says nothing about the shape of the response beyond grouping. For a metrics tool this is adequate but leaves real gaps an agent must guess at.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It partially does: it names the three grouping values (day, offer, link) and anchors earnings to UZS, but it never explains date_from/date_to semantics, what link_id or offer_id filtering does, or whether filter and group_by must be consistent (e.g. group_by=link with offer_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?

It names the concrete resource (aggregated performance metrics) and enumerates the measures returned — orders, approved, delivered, rejected, approval/delivery rates, earnings in UZS — plus the grouping dimensions. That is far more specific than the title 'Statistics'. It stops short of differentiating itself from the sibling get_insights, so it is clear but not sibling-aware.

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 use this versus get_insights or list_orders, and no exclusions or prerequisites. The only usage-adjacent fact is the default window ('last 30 days'), which tells the agent what happens by default but not when to choose this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds the useful scoping detail that results are for a period, but says nothing about pagination, whether archived campaigns are excluded by default, or auth requirements.

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 dense sentence with no wasted clauses, and the resource is front-loaded. It is efficient, though it reads as a payload summary rather than an instruction, so the actionable content is not 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 no output schema, the description usefully enumerates the returned fields including currency, which is above baseline. However, it omits the default period behavior and the include_archived semantics, so an agent still lacks enough to call the tool confidently across both parameters.

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

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

Schema coverage is only 50%: period has an enum with a documented default, but include_archived has no description in the schema and the description never mentions it. The description does not compensate for that gap, leaving one parameter semantically opaque.

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 resource (the partner's Meta ad campaigns) and enumerates the metrics returned, so an agent can identify the payload. It lacks an explicit verb and does not distinguish the tool from siblings like get_insights or get_ads_status, which cover overlapping ground.

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 use this tool instead of get_insights, get_ads_status, or list_orders, and no exclusions or prerequisites. The agent must infer usage from the field list alone.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so that ground is covered. The description adds genuinely new context: chronological ordering and cursor-based incremental fetching. It doesn't mention pagination limits or ordering stability, but the added value above annotations is real.

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, zero waste, with the resource/ordering front-loaded and the cursor-follow-up pattern as the second 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?

For a 4-param read feed with no output schema, the description covers ordering, event types, and the cursor return-value linkage. The main omission is the undocumented `limit` bound, but overall an agent has what it needs to call it correctly.

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

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

Schema coverage is 50%. The description usefully ties `after` to meta.next_cursor, and the schema documents `after`, `include_order`, and the `type` enum. However `limit` (bounds 1-200) is undocumented in both description and schema, so the description doesn't fully compensate.

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

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

States a specific resource (order events) and enumerates the event types (order.created, order.status_changed) plus chronological ordering. It's clearly distinct from single-order siblings like get_order, though it doesn't explicitly name them.

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

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

Explains a polling pattern (pass meta.next_cursor as `after` to get only new events), which implies ongoing-feed usage, but gives no explicit when-to-use versus alternatives or when-not conditions.

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

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

Annotations already disclose readOnly, idempotent, non-destructive, and non-open behavior. The description adds useful return-content context (clicks, orders, delivered counts, public URL), but it does not describe pagination behavior, scoping/auth requirements, or rate limits; with annotations covering safety, this is moderate added value.

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

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

The description is two compact sentences, front-loaded with the action and resource, and contains no redundant restatement. The second sentence adds useful return-content context without waste.

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 simple read-only list tool; annotations cover safety and the schema covers pagination and filtering parameters. Without an output schema, the description names the key returned fields and the public URL, though it could mention pagination defaults or result ordering explicitly.

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%, with page, limit, and offer_id all documented in the schema. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb, 'List', and clearly identifies the resource as the partner's tracking links (streams), including the metrics returned. It is readily distinguishable from siblings like get_offer, get_order, and search_offers because it is the listing endpoint for tracking links.

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

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

Usage is implied by the listing purpose and the note that each link has a public URL to share in ads, but there is no explicit when-to-use guidance, when-not guidance, or named alternative tool. A 3 reflects implied rather than explicit usage routing.

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

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

Annotations already carry the read-only/idempotent safety profile, so the description's added value is disclosing that phone numbers are masked and which fields are returned. It still omits pagination behavior and rate-limit/sync semantics, keeping it from 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 tight sentences, front-loaded with purpose followed by filters, with zero filler. The masking note is a single clause that earns its place.

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

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

For an 11-param, all-optional list tool with annotations covering safety and no output schema, the definition gives enough to call it correctly. The gaps (pagination, external_id, updated_since sync mode) are documented in the schema rather than the description.

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 55%, so the description must partially compensate; it maps 'link, offer, tracking click_id, dates, status, conversion_status' onto filter parameters in natural language. However it never mentions page, limit, external_id, or updated_since, and adds no format/semantic detail beyond the parameter names.

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

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

Specific verb+resource ('List the partner's orders') plus the returned fields (status, payout, payout_status), which lets an agent distinguish it from the singular get_order. It stops short of explicitly naming that sibling or stating the list-vs-single-record distinction.

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 filter list implies this is the discovery/query tool, but there is no explicit when-to-use versus get_order, nor guidance on pagination vs. using updated_since for syncing. Usage must be inferred from the filter enumeration.

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 readOnly/idempotent/non-destructive annotations already cover the safety profile, so the description's main added value is naming the returned fields (customer_price, payout, lead_bonus, stock, sale_rate_percent) and clarifying that only active offers are searched. It says nothing about pagination behavior, result ordering defaults, or what an empty result looks like, which matters since there is no output schema.

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

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

Three short sentences, zero filler, with the resource scope front-loaded and the return fields and sort tip following. Nothing needs trimming and nothing is 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 7-parameter read-only search with full schema coverage and clear annotations, the description covers what is searched and what comes back, which is enough to call it. It omits how results are paged/ordered beyond the sort enum and never positions itself against get_offer, leaving gaps an agent would have to probe for.

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 every parameter (page, limit, sort enum, search, min_payout, in_stock_only, min_sale_rate) is already documented in the schema. The description only echoes sort=best_selling, adding no syntax, format, or interaction details beyond the structured fields, 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?

States a specific verb and resource (search the catalog of active offers) and clarifies what an offer is with a parenthetical. It never distinguishes this bulk search from the sibling get_offer, so an agent must infer the difference from the name alone.

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

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

The line 'Use sort=best_selling to find offers that actually get delivered' gives one concrete usage tip, but there is no guidance on when to use search_offers versus get_offer, or when to skip it. Usage is implied by the sorting hint rather than stated as when/when-not rules.

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