guild_list

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

Without any annotations, the description carries the full burden and does so thoroughly: it discloses the transport limit motivation, exact results for matched/unmatched names, lack of pagination, one GET request, local row/byte limits, truncation reporting, and refusal of oversized records. This goes well beyond minimal disclosure.

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 front-loaded with the core purpose, but it becomes verbose and repeats the same idea: 'Other declared filters are forwarded without assuming their effectiveness' appears twice in slightly different wording. Some sentences ('Required inputs reflect tool policy...') add little actionable information.

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?

Despite no output schema and no annotations, the description covers the operational essentials: required name, result cardinality, no continuation pages, local truncation at 100 rows/256 KiB, truncation reporting, and oversized-record handling. The remaining gap is per-parameter semantics and full return fields, which prevents a 5.

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 clarifies that name must be explicit and that other declared filters are forwarded without guaranteed effectiveness, but it does not explain the semantics of sort_by, language, username, or membership_type. The parameter names are self-descriptive, but the agent gets no values or allowed options.

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 opening clause 'Search guilds by an explicit name filter' states a specific action and resource with a clear scope. It does not explicitly compare with sibling guild_find, but the emphasis on explicit name filtering differentiates the tool enough for selection.

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 explains when this tool is appropriate: a specific name is needed because unfiltered calls exceed the transport limit and unmatched names return no guilds. It cautions that non-name filters may not be effective, effectively telling the agent not to rely on them. It stops short of naming alternative tools, so it is not a 5.

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