getAffiliateUserInfo

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: authentication prerequisites, the 5-minute refresh cadence for deposit fields, the three covered business lines, the disclaimer that commission data is non-authoritative, and the meaning of totalWalletBalance range codes. This richly discloses behavior the annotations do not cover.

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 opens with a concise one-sentence summary and then uses tight, purposeful bullet points for caveats and field semantics. Every bullet adds operational value, such as permission requirements, data freshness, and balance range mappings, with no filler or repetition.

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

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

Given that there is no output schema, the description does a good job explaining key return-field semantics, data freshness, scope, and authoritative sources. However, the totalWalletBalance range mapping is slightly ambiguous and internally inconsistent, with tier '3' spanning 500–1000 USDT while tier '4' is simply '> 500 USDT', so the response semantics could still confuse an agent.

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

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

The input schema only defines uid as a string with no description, so the schema provides essentially no semantic coverage. The description compensates by explicitly defining uid as the Master UID of the direct client to query, which is the critical piece of information needed to invoke the tool correctly.

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

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

The description clearly states the tool queries detailed information for a specified direct client user under the affiliate account, enumerating specific data categories like VIP level, KYC level, balance range, and volumes. This is a specific verb plus resource and is clear enough to distinguish from the sibling getAffiliateUserList, though it does not explicitly name or contrast that alternative.

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 provides important usage context: it requires an API Key with affiliate permission bound to a Master UID, and clarifies that uid is the Master UID of the direct client. However, it does not explicitly state when to choose this tool over siblings such as getAffiliateUserList or how it compares to other affiliate-related query tools.

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