ghl_affiliate_list_payout_methods

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, so safety is covered; the description adds real value on top by disclosing that bank account values are truncated to the last four characters and specifying the auth token type and OAuth scope. It stops short of describing ordering, empty-result behavior, or error cases, so it is 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?

The behavior and the masking caveat are front-loaded in the first two sentences, with operational metadata (endpoint, scope, pagination) grouped afterwards. The endpoint/version/source line is boilerplate that costs a line without helping tool selection, 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?

No output schema exists, so the description carries the return-shape burden; it does so partially by noting masked bank values, and it covers auth, scope, and pagination. For a 4-parameter read-only list tool this is nearly complete, with only the overall result payload structure left implicit.

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% — skip and limit have no schema descriptions — but the description explicitly identifies them as pagination params and tells the agent to use them to page through full result sets, which is exactly the missing semantic. locationId and affiliateId are merely named in the endpoint path, adding little beyond the schema's own 'Location Id'/'Affiliate 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 and resource ('List the payout methods stored for an affiliate') and adds a concrete data-shape detail (bank account values returned as last four characters). An agent can immediately distinguish this from the sibling create/update/delete/mark-primary payout method tools.

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

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

Gives clear preconditions: requires a Sub-Account (location) token and the affiliate-manager.readonly scope, and notes that skip/limit should be passed to page through full result sets. It does not name a specific alternative tool, but the sibling set (create/update/delete/mark_primary payout method) makes the read-vs-mutate split self-evident.

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