list_custom_properties

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

No annotations are provided, so the description carries the full burden. It discloses the 'read-only' nature, which is a behavioral trait. However, it does not mention pagination behavior (despite having limit/offset parameters), default result size, or the shape of the returned data. For a list tool, some expectation of output structure would be helpful. The description adds a little beyond the schema but lacks depth.

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 a single, compact sentence that conveys the essential action and read-only nature without excess words. It is front-loaded and every word earns its place. Minimalism is a strength here, not a weakness.

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 the tool has four optional parameters, no output schema, and no annotations, the description is adequate but somewhat thin. It clarifies the action and read-only status but does not hint at what the response looks like (e.g., a list of property metadata), nor does it explain the purpose of 'include_values' beyond the schema. An agent might still call it correctly, but additional context about typical usage (e.g., 'use include_values to fetch stored values along with metadata') would improve completeness.

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, so each parameter has a meaningful description ('Max results', 'Text search over property names', 'Pagination offset', 'Include property values'). The tool description adds nothing about parameters beyond what the schema already provides. Since the schema covers all parameters, the baseline of 3 is appropriate; the description does not need to compensate for any gaps.

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 verb 'List' and the resource 'company custom properties', and additionally notes it is read-only. However, it does not explicitly differentiate from closely related siblings such as get_custom_property (which retrieves a single property) or list_custom_property_select_values (which lists values for a specific property). The purpose is unambiguous but not explicitly distinguished from alternatives.

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 no guidance on when to use this tool versus related tools like get_custom_property or list_custom_property_select_values. There is no mention of alternatives, prerequisites, or suitable scenarios. The read-only note hints at safety but doesn't direct the agent to choose this over a single-property lookup when only one is needed.

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