transaction_lookup

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

With no annotations, the description carries the full burden and does so richly: it never submits or retries, makes one logical GET, does not auto-fetch pages, limits array responses to 100 rows / 256 KiB with truncation reported, and refuses oversized records without partial fields. That is exactly the behavioral context an agent needs before calling.

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 purpose is front-loaded, but the body is a dense run-on mix of measurement notes ('measured 2026-10-11') and policy caveats. Most sentences carry information, though some are redundant framing rather than actionable guidance, hurting readability.

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 output schema and no annotations, the description still covers return shape (JSON-encoded string wire types, null result example), error behavior on unknown IDs, response limits, and truncation reporting. Nothing critical to a correct invocation is missing.

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. It adds genuinely useful semantics for trx_id (the <trx_id>-1/-2 continuation convention) and warns that declared filters are forwarded as supplied with effectiveness not implied, but it never explains what username or card_detail_id actually do, leaving two of three parameters opaque.

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 ('Read one game transaction by explicit trx_id') and explicitly differentiates scope from the sibling transaction_inspect, which reads the continuation records of a multi-op transaction. An agent can distinguish it from transaction_inspect without opening either schema.

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?

Names the alternative (transaction_inspect reads all <trx_id>-N records) and the condition that selects it, plus what happens on an unknown ID. It stops short of routing vs other transaction siblings like hive_transaction or cards_trx_lookup, so it is clear but not exhaustive.

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