List Contact Properties

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

The readOnlyHint annotation already indicates a safe read operation. The description adds behavioral context beyond this: it reveals that the tool is for obtaining property IDs and understanding configured custom attributes, and it instructs the agent to request user selection rather than presenting all IDs upfront, and to omit IDs and creation dates unless explicitly requested. This adds useful behavioral nuance without contradicting the annotations.

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 three sentences, each serving a distinct purpose: stating the function, explaining usefulness, and providing usage directives. It is front-loaded with the core action and avoids redundant wording. No unnecessary details or repetition of schema 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?

For a simple read-only list tool with optional pagination parameters and no output schema, the description adequately covers the core purpose and usage. It explains what the tool is good for (getting IDs, seeing custom attributes) and gives an explicit workflow. It does not describe the return format or pagination behavior, but the schema covers the latter, and the tool's low complexity reduces the need for further detail. Overall, it is sufficiently complete for an agent to invoke 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 input schema has 100% description coverage for all three parameters (after, limit, before), meaning the schema already explains their meaning and constraints. The description does not add further parameter-level details, but the schema is sufficient. Since the schema carries the burden, a baseline score of 3 is appropriate; the description's mention of 'all contact properties' could imply pagination behavior but the schema parameters already handle that.

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's purpose: 'List all contact properties from Resend.' It specifies the resource (contact properties) and the action (list), and distinguishes it from more targeted tools like get-contact-property by emphasizing that it retrieves all available properties. The phrase 'This tool is useful for getting property IDs and seeing which custom attributes are configured' further clarifies its intended use case.

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 gives explicit usage guidance: 'If you need a contact property ID, you MUST use this tool to get all available properties and then ask the user to select the one they want.' This clearly states when to use the tool and how to proceed. It also provides behavioral instructions ('Don't bother telling the user the IDs or creation dates unless they ask for them'), helping the agent know how to handle the results. No alternative tools are mentioned, but the conditional usage is strong.

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