AffiliateBase

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the minimal extra context that the result is 'compact' and scoped to 'the current account'; it discloses nothing about caching, freshness, 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?

A single sentence with no filler, and the key scoping qualifier ('current account', 'compact') is front-loaded. Nothing is wasted and nothing needs to be trimmed.

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

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

With an output schema present, the return shape is documented elsewhere, and the zero-parameter schema plus safety annotations mean few gaps remain. The one shortfall is that the description never positions this rollup relative to the list_* siblings an agent will also see in the toolset.

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 per the rubric the baseline is 4. There are no parameters whose meaning the description would need to clarify.

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 clear verb ('Return') and resource ('a compact reporting summary for the current account'), so the agent knows this aggregates reporting data rather than listing entities. However, it never distinguishes itself from the numerous list_* siblings or explains what the summary aggregates versus those tools.

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

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

There is no statement of when to call this versus the eleven sibling tools (list_commissions, list_payouts, list_affiliates, etc.), nor any prerequisites such as account context or permissions. The agent must infer that this is a high-level rollup rather than a detail 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the domain context that output is path-specific and limited to three named paths, but says nothing about auth requirements, return format, or limitations beyond what the annotations supply.

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 filler: the verb, the resource, and the distinguishing scope all appear before any qualifier. Nothing could be removed without losing 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 read-only, single-optional-parameter tool with full schema coverage and an output schema, the description is nearly sufficient, and the annotations carry the safety semantics. Only the relationship to sibling setup tools is unaddressed, which is a minor gap for a leaf lookup tool.

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

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

Schema coverage is 100% for the single enum parameter, which already documents the three allowed values and the payment_links default. The description merely restates the same enum values in prose rather than adding format or behavioral detail, 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 pairs a specific verb ("Return") with a specific resource ("install instructions") and enumerates the three supported install paths, so an agent knows exactly what it produces. It stops short of naming or differentiating itself from siblings such as verify_tracking_installation or read_setup_status, which share the setup/installation domain.

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: the three enumerated paths signal the scenarios in which the tool applies, but there is no explicit when-to-use, when-not, or routing to alternatives like verify_tracking_installation. An agent can infer intent but gets no guidance on how this fits alongside the other setup-related 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 this a read-only, idempotent, non-destructive, closed-world call, so the safety profile is covered. The description does add one meaningful behavioral trait beyond them: "account-safe" implies the payload is sanitized of sensitive values, which matters for an agent reasoning about what it can safely surface. It adds nothing about freshness, caching, or what the context 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?

A single tight sentence with no filler; the purpose is front-loaded. It is arguably too terse for the ambiguity it needs to resolve, but there is no wasted wording.

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 the annotations carry the safety profile. The remaining gap is disambiguation: with four setup-related siblings, the description never clarifies what makes this context different from install instructions or setup status, which is the one thing an agent most needs.

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 no parameter semantics to document and nothing for the description to compensate for. This is the baseline-correct case.

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

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

States a verb (Return) and a resource (setup context), so the action is identifiable. But "account-safe setup context" is vague about what is actually returned, and the description does nothing to separate it from sibling tools like get_install_instructions or read_setup_status, which sound like they cover the same 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?

The phrase "for an AI assistant helping install AffiliateBase" gives a loose scenario but never states when to call this tool versus get_install_instructions, read_setup_status, or verify_tracking_installation. No prerequisites, ordering, or exclusions are offered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description earns credit beyond that by clarifying the link is never a real affiliate's link (no data leakage) and that the tool may return instructions instead of a link, which is meaningful 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?

Two compact sentences with the core fact (test link, not a real one) front-loaded and the fallback behavior appended. 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 parameters and an output schema present, the description does not need to document return values. It supplies the one non-obvious thing an agent needs to know – that the output is a test link or creation guidance – which is sufficient for a zero-arg read tool.

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

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

The tool takes zero parameters, so the schema imposes no semantic burden and this dimension defaults to the baseline of 4. There is nothing further for the description to explain.

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 a specific verb and resource ('Return the setup test affiliate link') and clarifies the artifact is a test link, not production data. It is distinguishable from siblings like verify_tracking_installation or list_affiliates, though it 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?

The parenthetical about verifying tracking and the 'or explain how to create it' clause imply the intended use context, but there is no explicit when/when-not statement and no sibling is named as an alternative. Usage is inferable rather than 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description adds only the 'current account' scope and says nothing about default page size, result caps, filter combination behavior, or the sensitive-data gating implied by include_ban_details/include_contact_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?

A single front-loaded sentence with zero filler, but for a six-parameter, paginated listing tool it is under-specified rather than truly concise — brevity here costs 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?

An output schema exists, so return values need not be explained, but a 6-param list tool with pagination and state filtering gives the agent no information about result volume, defaults, or when the enum filter applies. The description leaves the agent dependent entirely on 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 coverage is only 50%: page, limit and state have no descriptions at all, and the description supplies no compensating detail about defaults, max page size, or filter semantics. The two documented include_* flags carry more guidance than the description does.

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 ('List') plus resource ('affiliates') with an explicit scope ('for the current account'), which is enough to separate it from list_campaigns, list_commissions, list_payouts and list_referrals by resource. It does not, however, explicitly contrast itself with those siblings or state what it returns.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g. get_dashboard_summary for aggregate counts vs. this for row-level listings), and no indication of pagination expectations. The only guidance lives in the schema, in the two include_* parameters.

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 fully covered. The description adds one genuine behavioral fact beyond that: only 'active' campaigns are returned, which is a filtering trait an agent could not derive from the annotations. It says nothing about default page size, result ordering, or what happens when no campaigns exist.

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

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

A single front-loaded sentence with no filler, and the scoping constraint is stated immediately. It is arguably too terse rather than too long, but nothing in it is wasted.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Still missing for correct invocation: pagination behavior/defaults, whether the list is truncated at 50 (the limit maximum), and any ordering guarantee. Adequate but with clear gaps.

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

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

Schema description coverage is only 33%: 'id' is documented, but 'page' and 'limit' have no textual descriptions (only numeric bounds). The description adds no parameter meaning at all, so it fails to compensate for the coverage gap the way a low-coverage schema requires.

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

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

States a specific verb (List) and resource (campaigns) plus the scope qualifier 'active for the current account'. It does not, however, distinguish itself from the many identically-shaped siblings (list_affiliates, list_commissions, list_payouts, list_referrals), leaving the agent to infer the choice from the resource 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?

There is no when-to-use guidance, no prerequisites, and no mention of any alternative tool or the condition that would select one. The agent must infer usage entirely from the tool 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low, and the description clears it by disclosing non-obvious behavior: totals span all pages despite pagination, by_affiliate is capped at 100 groups, that cap is not a cross-currency ranking, and truncation is signalled by by_affiliate_truncated. It still omits rate limits, permissions, and pagination semantics.

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

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

Purpose and ordering are front-loaded, and the five following sentences are dense and non-redundant, each resolving a real ambiguity (totals scope, affiliate cap, truncation flag). It is return-semantics heavy relative to guidance, but no sentence is filler.

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

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

An output schema exists, so explaining return values is not strictly required, yet the description's semantic notes (cross-page totals, truncation) are genuinely additive. Gaps remain around the vague 'recent' window, pagination interaction with limit=50, and no sibling differentiation, so an agent can invoke it but not confidently choose 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 only 20% (just id is described), so the description must compensate. It partially does: it identifies id/affiliate_id/state as the filter set and defines what 'due' means, but page, limit (max 50), and the other enum states (pending, processing, paid, voided) get no clarification in either place.

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

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

Opens with a specific verb and resource ('List recent commissions for the current account, newest first, with each affiliate's name'), so the agent knows exactly what comes back and in what order. It never distinguishes itself from the many list_* siblings (list_payouts, list_referrals, list_affiliates), which is the only thing keeping 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?

The description says nothing about when to choose this tool over list_payouts, list_referrals, or get_dashboard_summary; there is no when-to-use, when-not-to-use, or alternative named. The only implied context is 'for the current account', which is not a selection criterion among the siblings.

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

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

Annotations already cover the read-only/idempotent safety profile, but the description adds real operational context: totals aggregate across all pages rather than the current page, by_affiliate is capped at 100 groups selected by amount and is not a cross-currency ranking, and by_affiliate_truncated flags omissions. This pagination/truncation behavior is not derivable 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?

Purpose is front-loaded in the first sentence, followed by tightly packed semantic notes about totals and by_affiliate. It is dense but every sentence carries information about behavior or result shape; 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 an output schema present and annotations covering safety, the description's remaining burden is result-shape nuance, which it handles well (totals scope, truncation flag). The main gap is call-time guidance for filtering/paging parameters, which is minor for a read-only list tool.

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

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

Schema description coverage is only 20%, so the description must compensate, and it names the id/affiliate_id/state filters only collectively. It says nothing about page/limit behavior (e.g. max limit of 50, paging interaction with totals) or the format/semantics of the id filters, leaving the low-coverage parameters largely undocumented.

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

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

States a specific verb+resource ('List recent payouts for the current account'), adds ordering ('newest first') and an included field ('each affiliate's name'). It also distinguishes itself from list_commissions by explaining that a payout has its own state separate from its commissions' states.

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 semantics (payouts vs commissions) but there is no explicit 'use this when…' statement, no prerequisites, and no named alternative among the large set of list_* siblings. An agent can infer the context but is not routed to 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the default sort order ('newest first'), which is genuinely useful behavioral context, but says nothing about pagination behavior or what 'recent' means as a time bound.

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, front-loaded with verb and resource, with every clause (scope, ordering, included field) earning its place. 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?

An output schema exists, so return values need no explanation, but three of five parameters (page, limit, affiliate_id) are undocumented in both schema and description, and pagination/recency limits are unstated. Adequate for a simple list tool, but not complete.

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

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

Schema coverage is only 40%: id and state are documented in the schema, but page, limit and affiliate_id have no descriptions anywhere. The description mentions no parameters at all, so it does not compensate for the gap on filtering or pagination controls.

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

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

States a specific verb (List) and resource (referrals) scoped to 'the current account', and adds the ordering (newest first) plus what each row carries (affiliate's name). It is clearly distinguishable from list_affiliates/list_commissions by resource, though it never explicitly contrasts itself with those 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?

There is no when-to-use guidance, no stated alternatives, and no exclusions. The agent must infer from the name alone that this is the read path for referral records as opposed to list_commissions or list_affiliates.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety and repeat-call behavior are covered structurally. The description contributes the business trigger for the state change but says nothing about what 'confirmed' does downstream, whether it can be undone, or how the required idempotency_key and dry_run affect execution.

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 the verb and precondition up front and no filler. It is efficient, though it omits information that would earn its place given the untyped 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?

An output schema exists, so return values need no prose. However, for a mutation tool with 0% schema coverage the description should at minimum explain dry_run and the idempotency contract; both are absent, leaving an agent unable to call it precisely.

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% across three parameters, and the description mentions none of them. The required idempotency_key, the note field, and especially the dry_run flag (which meaningfully changes behavior) are left entirely unexplained.

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 pairs a specific verb ('Mark ... as confirmed') with a specific resource ('setup integration'), so the state transition is unambiguous. It implicitly separates itself from read-only siblings like read_setup_status and verify_tracking_installation, though it never names 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?

It states the precondition that selects this tool: use it 'after the merchant verifies the tracking script and Stripe client_reference_id handoff.' That is a clear usage context, but there are no exclusions and no pointer to what to call when the verification has not happened yet.

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 fully covered without the description. The description adds only the scope of the data (wizard progress plus activation health) and no further behavior such as freshness, caching, or account/permission 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 front-loaded sentence with no filler, restatement, or trailing caveats. Every clause contributes: the verb, the resource, and the account scope.

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, full annotation coverage, and an output schema carrying the return structure, the definition has little left to explain. The one residual gap is disambiguation from get_setup_context, which an agent could confuse with this tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool is 4. The improvised scoping phrase 'current AffiliateBase account' is the only parameter-like semantics and 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?

States a concrete verb ('Return') and a specific resource ('setup wizard progress and activation health'), which is more than a restatement of the name. However, it does not distinguish itself from the closely related sibling get_setup_context, so an agent can't fully resolve the two 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 description says what is returned but never when to call it or when to prefer an alternative such as get_setup_context or verify_tracking_installation. Usage is only weakly implied by the phrase 'current AffiliateBase account'; there are no explicit conditions 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only that the call yields verification signals and a recommended next action, with no mention of how verification is performed, asynchrony, or freshness of results. It adds some value but not rich 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?

A single front-loaded sentence with no filler; both the primary output artifact and the secondary recommendation are stated immediately. It is arguably terser than a tool with 11 siblings warrants, but nothing in the sentence is wasted.

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

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

An output schema exists, so return-value detail is legitimately offloaded, and with zero parameters and full annotation coverage there is little left to specify. The remaining gap is routing: nothing tells the agent how this differs from read_setup_status or get_setup_context, which is exactly what an agent needs in this catalog.

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 and the baseline is 4. Schema coverage is 100% on an empty object, and no call-site argument semantics 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?

The description names a specific verb ('Return') and resource ('tracking verification signals'), plus an additional output ('the next recommended setup action'), so the tool's function is legible. However, it never distinguishes itself from close siblings like read_setup_status or get_setup_context, which an agent must choose between in an 11-tool catalog. 'Signals' is also left undefined.

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 versus the overlapping setup/status siblings (read_setup_status, get_setup_context, get_install_instructions), nor any prerequisite or sequencing guidance. The agent must infer the selection criteria 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.