hail

Official

by hail-hq

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

List contacts

list_contacts

Read-onlyIdempotent

List the workspace's contacts: org members (with their phone/email) plus manually saved contacts. Use lookup_contact for name searches.

Instructions

List the workspace's contacts: org members (with their phone/email) plus manually saved contacts. Use lookup_contact for name searches.

    ``q`` optionally filters server-side (matches name/email/phone).
    ``limit`` caps the page (server default 100, max 500).

    Returns ``{"items": [{"id", "kind", "name", "phone_e164", "email",
    "role"}, ...]}`` — ``kind`` is ``"member"`` (id ``member:<user_id>``,
    ``role`` set) or ``"manual"`` (id is the contact's UUID, ``role``
    null).

Input Schema

Name	Required	Description	Default
`q`	No
`limit`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.29.0Oct 21, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already cover read-only, idempotent and non-destructive, so the bar is low, yet the description adds substantial context: server-side pagination behavior with a default of 100 and a hard max of 500, plus the two record kinds and their id formats (`member:<user_id>` vs UUID). That is exactly the kind of operational detail annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The scoping line is front-loaded, alternatives come second, and parameter detail follows in a natural order. The only waste is the return-shape block, which restates information an output schema already supplies, though it does add the `kind`/`id` semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with full annotation coverage, nothing needed to call it correctly is missing: scope, alternative, filter semantics, pagination caps and record-kind meaning are all present. The return-shape paragraph is redundant against the output schema but harmless.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and does: `q` is documented as a server-side filter matching name/email/phone, and `limit` is documented with both the server default and the maximum. These are semantics the schema (bare `string`/`integer`) provides nowhere.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource and defines the scope precisely: 'org members (with their phone/email) plus manually saved contacts.' It also points at the sibling tool that handles the search case, so the agent can distinguish list_contacts from lookup_contact without reading either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes name searches to lookup_contact, which is the key decision an agent faces among ~35 siblings. It stops short of a full when/when-not statement, and there is mild tension because `q` is also said to match name, so the agent must infer the boundary (filter vs. search).

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