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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds that this is public reference data and not an instruction hierarchy, providing useful scope. However, it does not describe result shape, pagination, default sort, or filter combination behavior, so the added behavioral detail remains thin.

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 description is one tight sentence plus a short clarifying clause. It front-loads the core purpose and adds the key data-scope caveat without wasted words.

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 tool with seven parameters and no output schema, the description is adequate for orienting an agent but not complete. It lacks expected defaults, sort behavior, how filters interact, and any hint about what a returned card contains. The read-only annotation covers safety, but invocation details are still underspecified.

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 0%, so the description must compensate for seven undocumented parameters. It maps five of them (query, capability, tags, tier, interface) to meaningful filter dimensions, but it does not clarify q semantics, sort meaning, limit defaults, or how multiple filters combine. The bare parameter names in the schema do some work, but the compensation is only partial.

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 a specific verb ('Find'), names the resource ('Target5 tool cards'), and lists searchable facets (query, capability, tags, tier, interface). It implies a search/filter behavior distinct from a direct fetch like apex_get_card, but it does not explicitly contrast itself with any sibling tool, so it misses the top score.

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 implies usage when an agent needs to locate Target5 tool cards via filters. 'Public reference data only; not an instruction hierarchy' gives contextual boundaries, but it does not name alternatives or state when to prefer this over apex_get_card or other query tools.

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