ebay_get_order_earnings_by_id

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

Beyond the readOnlyHint annotation, the description discloses critical behavioral constraints: the sell.finances.earnings.read scope is not requested by default and must be added to EBAY_OAUTH_SCOPES, approval is limited to US/CN/HK sellers with USD payouts, and EU/UK calls require Digital Signatures via EBAY_SIGNING_KEY_JWE and EBAY_SIGNING_PRIVATE_KEY. These are operationally important preconditions an agent could not infer from the annotation alone.

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 front-loaded with the core purpose and then spends its remaining sentences on non-obvious prerequisites. Despite being multi-sentence, every sentence earns its place given the auth, eligibility, and signing complexity.

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 Finances API tool with no output schema, the description explains the return contents and fully covers the complex authorization and regional-signing requirements. An agent has enough information to determine eligibility 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%, so the schema already fully documents both orderId and marketplaceId. The description mentions the orderId concept and the earnings returned, but adds no syntax or format details beyond the schema, which is the expected baseline.

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: 'Get earnings for one order from the eBay Finances API,' and enumerates the returned values (gross amount, expenses, refunds, net earnings). The 'one order' scope helps distinguish it from the summary/list siblings such as ebay_get_order_earnings_summary.

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 strong context for when the tool is usable, including the required optional scope, seller eligibility, and signing requirements for EU/UK sellers. However, it does not explicitly name alternatives like ebay_get_order_earnings or ebay_get_order_earnings_summary and state when to prefer them, so it falls short of full when/when-not guidance.

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