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

Annotations already cover read-only, idempotent, closed-world and non-destructive, so the safety profile is handled. The description adds genuinely useful behavioral context beyond that: results are alphabetical and are coverage-only with no participation status, which prevents an agent from misreading the roster as match data, and it signals the return payload (roster plus assessment URL).

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 lead clause is front-loaded and correct, but the single sentence is run-on and drags in tangents about engine scoring and client-added vendors that belong to other tools. The output sentence is short and useful; the middle clauses could be trimmed without losing the calling guidance.

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 an output schema present, the description needn't detail return values, and it correctly spends its words on scope and when-to-use. The one remaining gap is discovery of valid vertical_id values — nothing points the agent at list_verticals — but otherwise a one-parameter read tool is adequately covered.

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?

There is only one parameter, vertical_id, and schema description coverage is 0%, but its seven enum values are largely self-describing. The description says "one vertical" without explaining the ID format or where valid values come from (list_verticals is a sibling but is never mentioned), so it adds little meaning beyond the enum.

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 ("Lists the vendors PreShiftIQ covers in one vertical") plus scope qualifiers: alphabetical, catalog coverage only, no participation status. It also distinguishes itself from the match-scoring path and from client-added vendors, so an agent can tell it apart from siblings like my_matches or explain_matching without opening a schema.

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 an explicit trigger: "Use this when a user asks which vendors PreShiftIQ covers or whether a named vendor is covered." It implicitly routes match/participation questions elsewhere by stating those come from the engine's scoring, but it never names the sibling tool to use for those cases, so the exclusion is left partly to inference.

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