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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's real contribution is the non-obvious capping behavior: max 12 items returned even though limit can go to 20 at the API. That is exactly the kind of quirk an agent would otherwise get wrong. It does not explain ranking criteria or whether results are personalized.

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 what is returned and its cap, then the usage cue. The parenthetical earns its place because it documents the 12-vs-20 discrepancy. Slightly dense but no wasted text.

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?

An output schema exists, so return values need no explanation, but for a 7-parameter personalization tool with zero schema coverage the description is thin. It never says how age/gender/goals/fitness levels shape the ranking, nor what team_id scopes, which is essential to invoking it correctly.

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% across 7 parameters, so the description must carry the burden — but it only addresses limit. The six personalization/scope parameters (team_id, locale, end_user_age, end_user_gender, end_user_goal_ids, end_user_fitness_levels) are never mentioned, leaving the agent to guess whether recommendations are personalized or org-wide.

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 — 'ranked program recommendations from the organization library' — which is far more informative than the tautological title. An agent can distinguish it from list_team_programs or generate_program by the 'ranked/recommendation' framing, though the description never explicitly names those alternatives.

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?

'Use when the user wants instant program suggestions' gives a clear trigger condition, and 'instant' implicitly contrasts with generate_program. However, there is no when-not guidance, no mention of the parallel recommend_workouts sibling, and no stated prerequisites (e.g., whether team_id is needed for library scoping).

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