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

Annotations cover only readOnlyHint/openWorldHint, yet the description adds real behavioral context not available elsewhere: pages default to 20/max 200, counts.matched_filter is the true total, 'flows_truncated' signals a budget-trimmed page, and source_row_count/source_column_count are upper bounds because flows filter rows or emit fewer columns. These are non-obvious semantics an agent would otherwise get wrong.

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?

Purpose and routing are front-loaded in the first sentence, and the trailing sentences all carry operational payload (source counts, queryable, pagination, truncation). It is dense and slightly over-stuffed — the '20 default, 200 max' restates the schema — but there is very little 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?

No output schema exists, so the description carries the return-shape burden and does it: page size, counts.matched_filter, and the flows_truncated flag are all explained. For a 5-parameter, zero-required list tool, nothing an agent needs in order to call it correctly 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 description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: it warns to advance 'offset' rather than concluding the account ends, and to advance by the number RECEIVED rather than the requested limit. Enum semantics for 'only'/'type' are largely already in the schema.

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+resource ('lists the Dataddo FLOWS this account is connected to') and immediately frames it against the actual user questions it answers ('what business data do we have', 'what are we connected to'). It explicitly distinguishes itself from siblings describe_flow and list_entities, so an agent can route without opening schemas.

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?

Gives explicit alternatives and trigger conditions: use describe_flow for a single flow's column inventory, use list_entities for what is actually answerable. It also names the when-not case — a flow with queryable=false is 'connected and inspectable, not answerable'.

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