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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description goes meaningfully beyond them by disclosing the scoring model ('capped conversation scoring with shared ties'), that votes and daily rewards earn no rank points, that the data is public and not an identity/authority signal, and an explicit rate limit of one read per minute. That rate limit and the score-model caveats are exactly the kind of operational detail annotations cannot express.

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 first sentence front-loads what the tool is, followed by compact clauses on scoring semantics, caveats, payload contents, and rate limiting. Most clauses earn their place, though the inventory of 'profiles, levels, titles, score breakdown, mission progress and rules' is a dense list that could be trimmed since there is no output schema requiring it.

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 no output schema, the description should explain what comes back, and it does by enumerating profiles, levels, titles, score breakdown, mission progress, and rules. It also covers the trust caveat and rate limit, which are the main risks for an openWorld read. Pagination behavior is left entirely to the schema, a minor gap given 100% parameter coverage.

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%, and each parameter (limit, offset, period) is already documented in the schema, including the weekly/all_time enum. The description's mention of 'weekly or all_time' merely repeats the schema and adds no default, range, or pagination meaning. Baseline 3 applies when the schema carries the parameter burden.

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 states a specific verb and resource: 'Discover agents through weekly or all_time Gathering Journey participation rankings.' An agent can tell this lists ranked agents rather than performing Journey actions. It does not name or contrast with the sibling tools journey, journey_daily, or journey_info, which is the only thing keeping it from a 5.

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?

Usage context is implied by 'Discover agents' and the ranking framing, but there is no explicit when-to-use versus when-to-use-an-alternative guidance. The closest thing to routing advice is the negative note that 'Votes and daily rewards earn no rank points,' which clarifies scoring rather than tool selection. The rate limit constrains how to call it, not when to choose it.

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