request_join_alliance

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does disclose the single most critical behavior: this is a non-blocking async operation where the leader approves or rejects. However, it omits other behaviorally relevant details: what happens for duplicate/repeat requests, whether a pending request can be retracted, or any rate-limit/cooldown behavior. The approval-flow disclosure provides genuine value, but meaningful behavioral surface area remains undisclosed.

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, zero wasted words. The action-consequence relationship is front-loaded in sentence one, and sentence two gives a precise, actionable pointer to the discovery endpoint, including the raw path, which is opaquely useful to an agent dealing with a tool-wrapped API. Every word earns its place.

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 low-complexity, 3-parameter tool with a self-describing schema and no output schema, the description covers the lifecycle adequately: how to find the resource, how to request it, and what outcome to expect. The main gap is the absence of a note about membership exclusivity (e.g., implying the agent must not already be in an alliance, since leave_alliance exists as a sibling) — but this is a minor gap for such a simple tool.

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% — all three parameters (api_key, message, alliance_id) carry schema-level descriptions already. The tool description adds no parameter-level detail, but per the rubric that's acceptable since the schema does the heavy lifting. The description's implicit mention of the approval flow doesn't meaningfully add to the message param semantics. This is the expected baseline for complete schema coverage.

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?

Uses a specific verb ('Request to join') plus explicit resource ('an existing alliance') and immediately distinguishes itself from siblings like form_alliance or invite_to_alliance by disclosing the approval flow ('The alliance leader will approve or reject'). An agent could not confuse this with any other tool in the extensive sibling list. The inclusion of the exact endpoint in the second sentence further ties the purpose to a concrete action.

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?

Provides clear, actionable predecessor guidance: 'Use browse alliances (GET /api/v1/alliances) to find one' — an explicit alternative with a concrete endpoint. However, it doesn't explain when not to use this tool (e.g., if the agent is already in an alliance, given leave_alliance exists as a sibling, or to use form_alliance to create one). The context is clear and actionable, but exclusions are missing.

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