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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real context beyond them: it discloses the shape and variance of the result (enum values included; for write-only entities such as operatorSettings only the save() fields are returned), which is useful for interpretation.

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?

Two sentences, front-loaded with the primary purpose before the edge-case behavior. The second clause ('what delete() refuses') is slightly compressed but carries information that cannot be inferred elsewhere.

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, the description correctly spends its words describing what comes back (field list plus enum values, save/delete field sets). Minor gaps remain — the format of enum values and any RSQL syntax hints are unstated — but the tool is well-covered for a single-parameter lookup.

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% — the entity parameter already enumerates every valid dataset, including the write-only ones. The description reinforces the queryable-vs-write-only distinction but introduces no new syntax or format information, so baseline 3 applies.

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 ('List the filterable fields ... for a query dataset') plus the downstream purpose (building a valid RSQL filter). It also delineates the two entity modes (queryable vs write-only), so an agent can distinguish it from describeDataModel/describeConfiguration, which do not target RSQL filtering.

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 a clear when-to-use condition: call this before constructing a query filter, and for writable entities it explains how the output relates to save() and delete(). There is no explicit exclusion naming siblings like describeDataModel, but the use context is unambiguous.

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