Get Group Pending Requests

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

Goes well beyond annotations: states side effects are none, requires leader/officer membership, describes the return payload, and maps error codes (409 REVISION_CONFLICT, 403, 429, 401, INBOX_FULL rollback) to required agent behavior. The value is real, but the 'Use horizon_get_groups and horizon_get_group_pending to reconcile state' line is self-referential and slightly misleads about recovery paths.

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?

Front-loaded and labeled (Use when / Not for / Requires / Side effects / Returns / Errors), which makes the long error catalogue scannable. Slightly overlong and repetitive — the 429 no-automatic-retry rule is stated twice — and the self-referential recovery line costs it a point.

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 read tool with no output schema it supplies the return shape ({groupId,revision,invitations,joinRequests,serverTime}), the retained-entries guarantee, auth requirements, and error semantics, so an agent could invoke it correctly. Residual gaps are minor: the revision-conflict reconciliation guidance is ambiguous about which sibling actually performs the reconciliation.

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 coverage is 100%, so the baseline is 3, and the description earns an extra point by synthesizing the parameters into an auth story: sign in via horizon_signin_email/horizon_signin_anonymous, pass the accessToken as sessionToken, and pass the userId that signed in. It also clarifies 403/token-mismatch failure modes for those parameters.

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 ('Reads group pending requests') plus the session precondition, which is enough to place it alongside horizon_get_groups and horizon_get_group. It loses a point because the Errors paragraph confusingly names the tool itself ('horizon_get_groups and horizon_get_group_pending') as the thing to reconcile with, muddying the sibling boundary.

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?

Uses explicit Use when / Not for framing: 'opening a group screen or reconciling an uncertain action' versus 'unbounded group search, automatic pagination or using stale snapshots after a session change.' It also names prerequisites (leader/officer membership, session signin) so the agent knows when it cannot use this tool at all.

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