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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a state-changing, non-idempotent operation. The description adds that sessions are prepaid and that funding/querying follow, which is useful. However, it doesn't disclose side effects like session creation costs, wallet implications, or what happens on failure. The schema description mentions the handler defaults buyer_address to the caller's own platform wallet, which is a meaningful behavioral disclosure, but it's in the schema, not the tool description.

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 short but the first sentence is awkwardly phrased ('Buy per-query access to live data listings - first taste free via data_preview'), mixing marketing language with technical instruction. The second sentence is clear and actionable. It's concise but not optimally structured; the key instruction ('Open a prepaid session, then fund and query') is front-loaded enough, but the opening phrase could confuse.

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 6-parameter tool with no output schema, the description is thin. It tells the agent to open a session and then fund/query, but doesn't explain what a successful open returns, how to identify the session afterward, or what the parameters mean beyond the schema. The schema description provides substantial context (slug-or-UUID, buyer_address default), but the tool description itself leaves gaps. Sibling tools like data_session_fund and data_session_query imply a session ID is needed, but the description doesn't mention that output.

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 50%, and the description itself adds the key semantic that listing_slug or listing_id must be provided ('Provide exactly one of listing_slug or listing_id' is in the schema, but the description's 'Open a prepaid session' implies the listing context). The description doesn't explain max_queries, open_tx_hash, or proof_escrow_id, but the schema covers listing_id, listing_slug, and buyer_address. The description's workflow hint ('then fund and query') helps an agent understand that max_queries relates to session limits. Given partial schema coverage, the description adds moderate value but doesn't fully compensate for undocumented params.

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 ('Open a prepaid session') and resource ('live data listings'), and the title 'Open Data Session' reinforces it. It distinguishes from siblings like data_session_fund and data_session_query by focusing on opening a session. However, the opening line is somewhat garbled ('Buy per-query access to live data listings - first taste free via data_preview'), which muddies the purpose slightly.

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 gives a clear workflow: 'Open a prepaid session, then fund and query.' It also references data_preview as a free first taste, which implies when to use this tool vs previewing. It doesn't explicitly name alternatives like data_session_fund or data_session_query, but the sequential context ('then fund and query') provides clear usage guidance.

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