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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is known; the description nonetheless reinforces it and adds value beyond the annotations by explaining that writes happen inside the lambda via Database.GetConnection(), that rows come back newest-first, and that pages cap at 100. It stops short of describing the shape of the listing response or what 'switched on' and 'how full it is' concretely mean.

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?

There is little waste, but the first sentence is a long, comma-spliced run-on ('its records, shared by every version: whether it is switched on, how full it is, and its tables and views with their columns and how many rows each holds') that is harder to parse than the content warrants. The information is front-loaded, but the structure could be broken up for faster scanning.

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 read-only tool with no output schema and seven fully documented parameters, the description covers both modes (schema listing and paged row reading), the feature-scoped variant, page size, and ordering. An agent has enough to call it correctly without further context.

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 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: 'table' plus 'limit'/'offset' produces a page of that table's rows newest-first, capped at 100, and 'feature' swaps in a feature-scoped copy. That interaction between parameters is genuinely extra information, though ordering via 'order'/'ascending' is left to 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?

The description names a concrete resource (the lambda's database, its tables, views, columns and row counts) and a concrete mode switch (with table, a page of that table's rows). It is more specific than the bare verb+resource, but the opening is a dense noun phrase rather than a clean 'Read X' statement, and it never distinguishes itself from siblings like read_lambda or analytics.

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?

'Use it to see that migrations were applied and records were written' gives a real usage cue for the listing mode. There is, however, no guidance on when not to use it, no mention of the sibling tools (analytics, read_lambda, enable_data) that might read the same data, and no note that privateKey/auth is required to get anything back.

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