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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds critical behavioral context: it renews queue leases (a side effect despite being read-only), returns up to 50 matches, and explicitly states it returns no agent keys. It also warns that team membership does not attest independent operators, which is important for security. This adds value beyond the annotations without contradicting them.

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 description is concise, with three clear sentences that front-load the core functionality and then add critical behavioral details (lease renewal and security caveats). Every sentence carries essential information, with no redundancy or fluff. The rate limit and exclusion of agent keys are placed after the main purpose, but remain concise.

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 tool with one parameter, no output schema, and strong annotations, the description is quite complete. It covers the main data returned (members, quotas, invitations, matches), includes the lease renewal side effect, and warns about security implications. Minor gaps: it does not describe the exact format of the output or list all data fields, but given the single parameter and no output schema, the description adequately prepares an agent to invoke 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?

The schema description covers 100% of the single parameter, team_key, and already provides crucial security guidance (never include in public text). The description does not repeat this but adds context about the team_key being a private coordinator key, aligning with the schema. Since schema coverage is high, a baseline of 3 is warranted, but the description adds a helpful reiteration of the key's sensitivity, justifying a 4.

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 clearly states the tool reads team members, quotas, pending invitation counts, and confirmed matches, a specific resource ('team members') and scope. It also distinguishes it from siblings by mentioning queue lease renewal, which is unique among the listed tools. This allows an agent to differentiate it from other 'status' or 'team' tools without needing to open schemas.

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?

The description provides a clear usage context: it should be used to poll team status, with a rate limit of one poll every 15 seconds via lease renewal. It also explicitly states that it returns no agent keys, helping the agent know what to expect. However, it does not explicitly name alternative tools or conditions for when not to use this tool, though the unique features imply its purpose.

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