contactFilters

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

No annotations are provided, so the description must fully disclose behavior. It lists filter types and mentions that 'locations' requires a parameter, but fails to explain return format, pagination, authentication needs, or error handling. Moreover, the claim that 'requires locationSearchText parameter' conflicts with the schema where locationSearchText is not required, causing potential confusion.

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 concise, with a single introductory sentence followed by a bullet list summarizing all supported filter types. It is front-loaded and contains no unnecessary words or repetition.

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 simple nature of the tool (retrieving filter lists), the description covers the main behavior and parameter linkage. However, it omits details about the response format, how results are structured, and the exact behavior for each filter type (e.g., whether departments returns labels or IDs). The parameter requirement inconsistency also detracts from 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% coverage with parameter descriptions, so baseline is 3. The description adds value by linking each filter type to its purpose and clarifying that 'locations' needs locationSearchText. However, the statement that locationSearchText is required contradicts the schema's optional definition, slightly undermining clarity.

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?

Description clearly states it retrieves available filter values for contact search and explicitly lists five supported filter types (departments, seniority, etc.), distinguishing it from the sibling 'companyFilters' tool. The verb 'Get' and resource 'filter values' are specific and unambiguous.

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 usage when populating contact search filters by listing the types, but it does not specify when not to use this tool or mention alternatives (e.g., using companyFilters for company-related data). No explicit usage context or exclusion criteria are provided.

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