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

With no annotations, the description carries the full burden. 'Queries the state' implies a safe read, and it notes the result is 'a json object,' but it says nothing about possible state values, error conditions, rate limits, or cost. It adds only minimal behavioral context beyond the read implication.

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 core purpose is front-loaded and the @param block earns its place, but the opening line and the 'Step 4. Optional. Queries the state...' line restate the same purpose verbatim. The '@return: a json object' line 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?

For a state-query tool with no annotations, no output schema, and 0% parameter coverage, the description should explain what states can be returned, since 'a json object' conveys nothing. Parameter documentation is complete, but the query semantics remain thin.

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 description must compensate, and it does document all four parameters. The account_fk note (a database ID, not an account address, must not be 0) and the payment_id provenance ('returned from withdraw/to_ott') add real meaning the schema lacks.

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 ('Queries the state of an OTT Mobile withdrawal') and situates it in the withdraw_to_ott flow via payment_id. It is distinguishable from siblings like withdraw_to_ott (the action) and withdraw_to_ott_quote, though it never names them 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?

'Step 4. Optional.' plus the payment_id-from-withdraw/to_ott reference gives clear flow context for when to call it. However, it never states when not to use it, what the alternatives are, or how to interpret different states, so usage is implied rather than explicit.

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