List Group Relationships

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description still adds meaningful context beyond that: required OAuth scope (groups:read) and the bounded page_token retrieval model. It does not describe the shape of returned relationships, but with annotations carrying the safety story this is a solid contribution.

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?

Four short sentences, front-loaded with purpose, then read semantics, pagination, and scopes. Nothing is padded, though the opening sentence duplicates the title, which is a minor waste.

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 an eight-parameter optional-filter list tool with no output schema, the description covers reading, scoping, and pagination adequately. It leaves two notable gaps: what a 'group relationship' actually represents and how this endpoint relates to its siblings list_groups/get_group_relationship. Minimum viable, not 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 description coverage is 100%, so all eight parameters are already documented in the schema, including count, group, owner, account, and pagination fields. The description mentions page_token retrieval but adds no syntax or semantics beyond what the schema states. Baseline 3 is appropriate when the schema does the heavy lifting.

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 gives a specific verb and resource ('List Group Relationships'), which is enough to know it is a collection read. However, the sentence basically restates the title, and it does not distinguish this list endpoint from close siblings such as get_group_relationship or list_groups. Clear purpose, but no sibling differentiation.

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?

There is no when-to-use guidance: nothing says when to call this versus get_group_relationship, list_groups, or get_group. 'Reads Calendly data' is not actionable usage context. The only hint toward usage is the scopes line, which is a prerequisite rather than a routing rule.

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