Pick the right way in
| You're building | Use |
|---|---|
| An AI agent that decides what to do | The MCP server. The model reads each tool's description and picks what it needs. |
| Code with fixed steps: a sync job, a webhook handler, a dashboard | The REST API. Same actions, plain HTTP, and safe retries. |
| A custom agent with your own model calls | Either. MCP SDKs list the tools for you; or describe a few REST calls as your own tools. |
Give each agent its own key
One key per agent or integration, named after it, with the least access that works:
- Read-only for anything that answers questions or reports. It can't change anything, whatever the model decides to do.
- Full access only when it must make changes. Over MCP the agent then sees the tools that change things too.
Keys act as the person who made them, so an agent never sees more than its owner. Admins can see each key's traffic under Admin → API and revoke it there.
Ground answers in your knowledge
For questions about how your organization works, have the agent:
- Call
search_knowledgewith the whole question, not keywords. Search matches meaning. - Call
read_documentfor the documents that matter, to read beyond the passage. - Cite the
urlof each document it used, so people can check. - Call
who_knowsto find someone to ask when the documents don't cover it.
A system prompt line that works well:
When asked how we do something, search PlaybookOps knowledge first and answer only from what you find. Link each document you used. If nothing covers it, say so and suggest who to ask using who_knows.
Make changes safely
- Read before you write. Call
get_projectfor the board's groups and columns before setting values, andlist_peoplebefore assigning someone. - Don't repeat changes. Over REST, send an
Idempotency-Keywith every change (how). Over MCP, check whether something exists before creating it again. - Handle limits. On
429, waitRetry-Afterseconds. On402, tell the person their organization is out of AI credits. - Let the app notify people. Changes made through the API behave like changes in the app: assignees are notified and automations run. Your agent doesn't need to send its own messages.
Docs for models
These docs come in plain text for models and coding agents:
/llms.txtlists every page with a one-line summary./llms-full.txthas every guide in one file.- Every page is also available as Markdown: add
.mdto its address. /v1/openapi.jsondescribes the API in OpenAPI 3.1, for code generators.