guild_members

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

With no annotations, the description carries the full load and does so exceptionally. It reveals that membership status is not inferred, that limit/offset are ineffective and unsupported, that only one logical GET is made without auto-fetching continuation pages, and that array responses are capped at 100 rows / 256 KiB with truncation reported. It also notes that oversized records are refused without partial fields. These are concrete, non-obvious behaviors.

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 dense but every sentence carries distinct information: purpose, empirical results, paging, request behavior, input policy, and array limits. It is front-loaded with the core purpose. One sentence ('Required inputs reflect tool policy...') is somewhat vague and could be cut, but overall it is well-structured for such a behaviorally complex tool.

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?

Given there is no output schema, the description covers a lot: required input, optional filter, paging absence, request pattern, truncation, and refusal behavior. The only notable gap is that it never specifies the shape or fields of the membership rows themselves; an agent knows they are rows but not their content. Still, for a read-only lookup of this type, the description is nearly complete.

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 0%, so the description must compensate. It does: it clarifies guild_id is required and explicit, explains that status is forwarded as supplied and not inferred, and documents the observed behavior of limit/offset (ineffective). It does not enumerate possible status values, but it adds meaningful semantics beyond the bare schema.

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 opens with a specific verb and resource: 'Read guild membership rows for an explicit guild_id.' This clearly distinguishes the tool from siblings like guild_list or guild_find, which target guild objects rather than membership rows for a known ID. The requirement of an explicit guild_id is stated up front.

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 implies the use case: you call this when you have a concrete guild_id and need its membership rows. It also explains the optional status filter with observed results. However, it never explicitly names alternatives or conditions when another tool (e.g., guild_find or guild_contributions) should be used instead, so the guidance remains implied rather than explicit.

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