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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: it discloses that only metadata is returned and never the secret value, and it states the important limitation that secrets cannot be created or set through this assistant — both of which materially shape how an agent should act.

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?

The primary purpose and scope are front-loaded in the first sentence, with use-case guidance and limitation disclosure following in the second. The brief definition of what a secret is earns its place because it grounds the agent in domain semantics, and every sentence carries distinct information. Slightly dense but not wasteful.

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 simple list tool with an output schema present, zero required parameters, and safety annotations already covering the mutation profile, the description covers purpose, scope, usage context, domain meaning, and a key limitation. The pagination mechanics are implicitly referenced via page_token's schema description, so nothing critical 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 all three parameters (page_size, page_token, slug_prefix) are already documented in the schema. The description reinforces the slug concept by explaining that api templates reference secrets by slug, which adds minor semantic context for slug_prefix, but it does not need to compensate for any schema gap. Baseline 3 is appropriate.

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 opens with a specific verb+resource+scope: 'List the secrets belonging to the authenticated tenant.' It further distinguishes itself from sibling get_secret by clarifying it returns metadata only, and from secret creation by stating secrets cannot be created or set through the assistant. An agent can unambiguously determine what this tool does and what it does not do.

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 a concrete use case — discovering which secrets exist so an api template's auth.secret can be wired to the correct slug — and provides an explicit fallback path (send the user to the dashboard) when the needed secret doesn't exist. It does not explicitly name the sibling get_secret as an alternative for retrieving a specific secret's details, which would have made the routing complete.

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