Contacts API

Search and access user's contact information.

contacts.search()

Find contacts by name, email, or phone number.

Parameters

Parameter	Type	Required	Description
`query`	string	Yes	Search query (name, email, phone)
`limit`	number	No	Max results (default: 10, max: 50)

Example

const contacts = await tools.contacts.search({
  query: "Alice",
  limit: 5
});

// Returns:
[
  {
    id: "contact_abc123",
    name: "Alice Johnson",
    emails: ["alice@company.com", "alice.j@personal.com"],
    phones: ["+1-555-0123"],
    organization: "ACME Corp",
    title: "Product Manager"
  },
  {
    id: "contact_xyz789",
    name: "Alice Smith",
    emails: ["asmith@example.com"],
    phones: [],
    organization: null,
    title: null
  }
]

Use Cases

Auto-complete Recipients

Help users compose messages by suggesting contacts as they type.

const suggestions = await tools.contacts.search({ query: "ali" });
// Show: Alice, Alicia, etc.

Meeting Attendees

Find contact emails when scheduling calendar events.

const results = await tools.contacts.search({ query: "team" });
const attendees = results.map(c => c.emails[0]);

Smart Suggestions

Context-aware contact suggestions based on user's relationships.

const frequent = await tools.contacts.search({ 
  query: "", 
  filter: "frequent" 
});

Complete Example

export async function handleIntent({ intent, context, tools }) {
  if (intent.action === "send_to_contact") {
    const { name, message } = intent.parameters;

    // Step 1: Search contacts
    const contacts = await tools.contacts.search({ query: name });

    if (contacts.length === 0) {
      return {
        type: "error",
        title: "Contact not found",
        description: `No contacts match "${name}"`
      };
    }

    // Step 2: Disambiguate if multiple matches
    if (contacts.length > 1) {
      return {
        type: "suggestion",
        title: "Which contact?",
        items: contacts.map(c => ({
          title: c.name,
          subtitle: c.emails[0],
          action: { type: "select_contact", contactId: c.id }
        }))
      };
    }

    // Step 3: Send message
    const contact = contacts[0];
    
    await tools.approval.request({
      action: "send_message",
      title: `Send message to ${contact.name}`,
      details: {
        to: contact.emails[0],
        message: message
      }
    });

    await tools.messages.send({
      to: [contact.emails[0]],
      subject: "Message from METAOS",
      body: message
    });

    return {
      type: "result",
      title: "✅ Message sent",
      description: `Sent to ${contact.name}`
    };
  }
}

Required Capabilities

{
  "capabilities": [
    "contacts.read"   // for contacts.search()
  ]
}

Error Codes

CAPABILITY_DENIED

User has not granted contacts.read capability.

INVALID_PARAMETER

Query parameter is missing or empty.

🔒 Privacy Note

Contact data is highly sensitive. Only request contacts.read if absolutely necessary for your agent's core functionality. Be transparent about how you use contact data in your privacy policy.