Module 10 — Build and Extend · Lesson 10.4
Building Your Own App
The manifest, the tool endpoint, versions, review and rollback
~11 min
What you'll learn
- Describe the anatomy of a Kavanah app
- Create an app from the starter manifest and upload a version
- Submit for marketplace review and track its state
- Design tools that an agent can actually use well
The app platform exists so a capability Kavanah does not have can be added by someone who does have it — without forking anything, and without users handing out API keys. If you have a system worth exposing to an agent, this is the shape.
What an app is
An app is a JSON manifest plus a server you host.
The manifest declares: a slug, the scopes it requests, the agent tools it provides, and a tool endpoint URL.
The tool endpoint is yours. When the agent uses one of your app's tools, Kavanah calls that URL. Your server does the work and returns the result.
That division is the important part. Kavanah handles discovery, installation, scope approval, governance and the agent loop. You handle what your tool actually does. There is no Kavanah code to write and nothing to deploy on our side.
The /docs 'Building apps' page carries the full manifest reference and the app SDK.
The console
The Developer console is reached through Apps → the Build tab. It is not in the sidebar.
Create an app — the starter manifest shows the required shape. Edit the manifest: tools, scopes, endpoint. Upload it as a version.
Submit a version for marketplace review and watch its review state. Once approved, it appears in the marketplace for other workspaces to install.
And roll back: you can set the app's current version to an earlier one. This is the release-safety net, and it is worth knowing exists before your first bad version rather than after.
Designing tools an agent can use
This is where most first apps go wrong, and it is not about code.
Name tools for what they accomplish, not for your internal API. A model chooses a tool by reading its name and description; `get_customer_health_summary` is chosen correctly far more often than `v2_cust_agg`.
Write descriptions for a reader who does not know your system. Say what the tool does, when to use it, and what it returns. The description is the entire basis on which it gets picked.
Keep parameters few and typed. Every optional parameter is a chance for the model to guess, and a guess in a parameter is a wrong call that looks like a right one.
And return something readable. A tool returning a wall of JSON forces the model to interpret; one returning a short structured summary is used correctly more often.
The general principle: your tools are being read, not invoked from documentation. Optimize for being understood on first reading.
Scopes and trust
Request the minimum scopes your tools actually need.
This is partly ethics and mostly adoption: an app requesting broad access for a narrow function gets declined at the install screen by exactly the careful admins you most want as users.
Also be explicit, in your app's description, about what data reaches your server and what you do with it. Users are approving a data flow as well as a capability, and saying so plainly is a competitive advantage rather than a disclosure burden.
Versioning discipline
Treat a published version as immutable. Changing what a tool does under an existing name breaks workspaces that built a workflow on it, silently, with no error anyone can trace.
If a tool's behaviour needs to change materially, add a new tool rather than redefining the old one, and deprecate the old one in its description.
And test the rollback path before you need it. Knowing you can revert is what lets you ship.
Build one
- 1
Apps → Build tab. It has no sidebar entry, which is why most people never find it.
- 2
Create an app from the starter manifest
It shows the required shape: slug, scopes, tools, tool endpoint URL.
- 3
Read the manifest reference in the docs
The 'Building apps' documentation page carries the full reference and the SDK.
- 4
Name and describe your tools for a stranger
The description is the entire basis on which the model picks the tool. Write it for someone who does not know your system.
What to watch
- Tool selection accuracy
- How often the agent picks the right tool from your app for a given request.
- Healthy signal: Nearly always. Misses are almost always a naming or description problem rather than a model problem.
- Install-to-active rate
- Share of installs where the app's tools actually get used.
- Healthy signal: High. A gap usually means the workspace-level or per-app agent switch was never turned on.
- Scope decline rate
- How often admins abandon the install at the scope approval screen.
- Healthy signal: Low. A high rate means you are asking for more than your function justifies.
Key takeaways
- ·An app is a JSON manifest plus a tool endpoint you host — Kavanah handles the rest.
- ·The Developer console is behind Apps → Build; it handles versions, review and rollback.
- ·Tools are chosen by name and description — write them for a stranger, not for your API.
- ·Few, typed parameters and readable returns produce far better tool use than rich JSON.
- ·Treat published versions as immutable; add a new tool rather than redefining an old one.
Last in this module: driving the whole product programmatically, from a script or from your terminal.