list_objects

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool returns approximate row counts (not exact), mentions it is 'Cheap' (a performance trait), and lists the scope of object types covered. It doesn't discuss permission requirements or error behavior, but the 'Cheap' and approximate-count disclosures are genuinely useful behavioral context beyond schema.

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?

Three sentences, each adding value: scope+behavior, filtering instructions with example, and sibling differentiation. The front-loaded first sentence is information-dense. Minor deduction for somewhat technical phrasing ('a SQL LIKE name_pattern') that could be more direct, but it's economical and well-organized.

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?

The tool has an output schema (so return values are covered there) and 3 params with 0% schema coverage, but the description documents the main semantics of the two filter params and the scoping behavior. It's complete enough for an agent to select and call correctly. Minor gaps: no mention of whether schema must exist, ordering of results, or pagination/limits, but the 'Cheap' note and existing structure make this adequate.

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 0%, so the description must compensate. The description explains the semantics of object_type (filter by type, with allowed values implied by the sibling mention of table/view/etc.) and name_pattern (SQL LIKE pattern, with example 'order%'). However, the 'schema' parameter is never described beyond being the target namespace, and the anyOf/null structure isn't fully clarified. The description adds meaningful value but doesn't fully cover all 3 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 uses specific verbs and enumerates the exact resource types (tables, views, materialized views, sequences, foreign tables) in a schema. It clearly distinguishes from siblings by mentioning the full shape of a single relation belongs to describe_object, and the general-purpose execute_query is implied as an alternative for arbitrary queries.

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 explicit guidance on when to use this tool vs describe_object ('Prefer describe_object for the full shape of a single relation'), provides filtering examples with object_type and SQL LIKE name_pattern ('order%'), and notes it is 'Cheap' so agents know it's safe to call. The when/when-not guidance is explicit and actionable.

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