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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description still adds meaningful behavioral context: tables sync across stations and work OFFLINE, they are the only sanctioned persistence (browser storage is rejected by validate_flow), and some blueprint-owned tables are invisible here. It does not disclose result size, pagination, or ordering, which keeps it short of a 5 for a listing endpoint.

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?

Front-loaded with the core action, then layered caveats in descending priority. The sentences each carry information, though the domain primer on what custom tables are and the closing renderClient API note are somewhat tangential to a pure listing call, making it longer than strictly necessary.

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?

No output schema exists, and the description compensates by stating what is returned ('tables with their column schemas') plus the important caveat that the list can be incomplete for selfPersisting blueprints. Combined with annotations covering the safety profile and full schema coverage on the one parameter, an agent has everything needed to call this 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?

There is a single optional parameter (hubToken) with 100% schema description coverage, so the schema already explains it fully. The description adds no parameter-level detail, which is the expected baseline of 3 when the schema does the heavy lifting and the parameter is a fallback auth token.

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 first sentence gives a precise verb+resource+payload: 'List your organization's custom data tables with their column schemas.' It is clearly distinguishable from siblings flow_create_custom_table, flow_update_custom_table, and flow_list_extension_custom_tables, which the description implicitly scopes away from by talking about org-owned tables.

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 states exactly when to call it ('Call this before create_custom_table to reuse an existing table instead of duplicating one') and routes to alternatives for adjacent needs (search_blueprints for new functionality, lookup_command_frame for runtime data access). It even covers the when-not case: a selfPersisting blueprint's tables may be absent, and 'their absence is never a reason to create lookalikes.'

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