DEV Community

Cover image for 5 Nylas CLI commands every AI agent should have access to
Qasim Muhammad
Qasim Muhammad

Posted on

5 Nylas CLI commands every AI agent should have access to

#aiagents #mcp #cli #tutorial

Adding email and calendar tools to an AI agent is mostly an exercise in restraint. Give it 50 commands and the agent gets confused. Give it 5 carefully-chosen ones and it punches above its weight.

After running agents against the Nylas CLI for a few months, these are the five I keep coming back to. Each gets exposed via MCP (nylas mcp install) so the agent can call them directly.

1. nylas email send

The most-used tool by a wide margin.

nylas email send \
  --to alice@example.com \
  --subject "Re: budget review" \
  --body "Approved. See you Friday."
Enter fullscreen mode Exit fullscreen mode

Why it ranks first: every agent task that touches the outside world eventually needs to communicate the result. A pull request shipped, an order placed, a bug filed — someone wants to know. Email is the lowest-common-denominator channel.

Agent prompt pattern that works:

When you complete a task that affects another person, send them an email summary. Use nylas email send with their address from the ticket. Subject line should match the ticket title. Body should be 2-3 sentences max.

2. nylas email list --json

Reading is half of email. The --json flag matters: agents parse JSON, not prose tables.

nylas email list --unread --limit 20 --json | jq '.[] | {from: .from[0].email, subject, snippet}'
Enter fullscreen mode Exit fullscreen mode

Filters that matter most:

  • --unread — only what is new
  • --from "alice@example.com" — scope to a sender
  • --query "invoice" — text search across subject + body
  • --in folder/Inbox — provider-specific folders

A common pattern: every 5 minutes, the agent runs nylas email list --unread --json, sees 0-5 new messages, and decides whether each needs human attention.

3. nylas calendar events list

Most "schedule a meeting" requests fail because the agent does not know what is already on the calendar. Give it visibility.

nylas calendar events list \
  --start "2026-05-04T00:00:00Z" \
  --end "2026-05-11T00:00:00Z" \
  --json
Enter fullscreen mode Exit fullscreen mode

This returns a week of events as JSON the agent can reason over. Pair with nylas calendar find-time for "find a 30-minute slot when alice@ and bob@ are both free":

nylas calendar find-time \
  --participants alice@example.com,bob@example.com \
  --duration 30 \
  --window-start "2026-05-04T09:00:00-05:00" \
  --window-end "2026-05-08T17:00:00-05:00"
Enter fullscreen mode Exit fullscreen mode

4. nylas contacts search

This one surprised me. The agent constantly needs the answer to "what is the email of the person whose name is X". Without contacts access, it asks the user. With contacts access, it just looks up.

nylas contacts search --query "alice" --json
Enter fullscreen mode Exit fullscreen mode

Returns matches against name, email, and company. Three-letter queries work; the search is fuzzy.

A specific pattern that pays off: when the agent drafts an email, it can run a contacts lookup on every name mentioned in the body to verify it has the right email. "Email Alice about the launch" without a contacts tool means asking which Alice. With the tool, the agent disambiguates by company or role.

5. nylas agent account create

For tasks that involve a new identity (testing flows, signing up for services, isolating per-PR test inboxes), the agent should be able to provision its own.

nylas agent account create test-$(uuidgen)@yourapp.nylas.email --json
Enter fullscreen mode Exit fullscreen mode

Pair with nylas agent account delete to keep things tidy:

nylas agent account delete $GRANT_ID --yes
Enter fullscreen mode Exit fullscreen mode

This is the meta-tool. The agent can spawn one-shot inboxes for E2E tests, signup automation, or cross-account verification. Most other "AI agents and email" stacks miss this primitive.

What I deliberately left off

Five more commands that are great but did not make the cut for a default agent install:

Command Why excluded
nylas email mark-starred Personal preference; agent has no opinion about importance
nylas email delete Destructive; require human confirmation by default
nylas calendar events create Powerful but easy to misuse — most teams want a human in the loop
nylas webhook create Better as a one-time setup by the operator, not an agent action
nylas agent rule create Same — policy and rules are operator-level config

A safer agent surface is a smaller surface. Add commands as the agent earns trust.

How to install just these five

When the MCP install gives you the full tool set and you want to scope it down:

// In your AI tool's MCP config, after running `nylas mcp install`
{
  "mcpServers": {
    "nylas": {
      "command": "nylas",
      "args": ["mcp", "serve"],
      "env": {
        "NYLAS_MCP_TOOLS": "email_send,email_list,calendar_events_list,contacts_search,agent_account_create"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The NYLAS_MCP_TOOLS env var allow-lists which tools the server exposes. Everything else stays hidden from the agent.

The takeaway

The single biggest mistake I see in agent installs: throwing every available tool at the agent and hoping it picks. Better to start with five well-chosen ones and add more as the workflow demands. Send, list, calendar, contacts, agent-account — the five that cover 90% of real agent tasks involving email.

Next steps

Top comments (1)

Collapse
 
peacebinflow profile image
PEACEBINFLOW •

The exclusion list is the part that actually teaches the most about agent design. "Email delete" being excluded because it's destructive, not because it's hard to implement — that's not a technical decision, it's a trust boundary. And the fact that it's documented means the team has thought about what the agent could do and deliberately chosen to keep those capabilities behind a human gate.

What's interesting is that this kind of deliberate constraint is the opposite of how we usually build APIs. When you're designing for human developers, you expose everything and trust them to use good judgment. The surface area is a feature. With agents, surface area is a liability. Every exposed command is a potential misfire, and the agent doesn't have the contextual judgment to know when "delete" is appropriate versus catastrophic.

The NYLAS_MCP_TOOLS allow-list is a nice implementation detail, but the real pattern here is the design instinct to start minimal and add only as trust is earned. That instinct runs counter to most platform adoption incentives — platforms want you using everything, because breadth of usage drives stickiness. I wonder if we'll see a tension emerge between platform incentives (expose all the tools, let the agent figure it out) and operator instincts (lock it down, open up slowly), and which side wins out as these agent integrations become more common. My guess is the operators who are currently cleaning up after over-permissioned agents will start demanding allow-lists as a default, not an afterthought.