Hatchable
Server Details
Build, deploy, and host full-stack web apps from any MCP client. DB, auth, storage, cron included.
- Status
- Unhealthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.3/5 across 33 of 33 tools scored. Lowest: 3.2/5.
Most tools have distinct purposes: create_project, deploy, write_file, run_code, etc. However, there is slight overlap between write_file and write_files, and between upload_file and import_file_from_url, but descriptions clarify the differences.
Tool names predominantly use verb_noun pattern (e.g., create_project, list_files, set_env). A few tools like grep and deploy are less descriptive but still consistent. Overall pattern is clear and predictable.
33 tools is on the high side, covering a broad platform surface. While each tool serves a distinct purpose, the count feels heavy for a single server, potentially overwhelming agents.
The tool set comprehensively covers the Hatchable platform lifecycle: project creation, file management, deployment, database operations, code execution, logging, and configuration. No obvious gaps for typical workflows.
Available Tools
32 toolscreate_projectADestructiveInspect
Create a new Hatchable project. This generates a URL slug, creates a dedicated PostgreSQL database, and returns the project ID and URLs. Call this first before writing files or creating tables.
Project structure
public/ static files, served at their file path
api/ backend functions — each file is one endpoint
hello.js → /api/hello
users/list.js → /api/users/list
users/[id].js → /api/users/:id (req.params.id — one segment)
docs/[...path].js → /api/docs/*path (req.params.path — string[], catches multi-segment)
_lib/ shared code, not routed
migrations/*.sql SQL files, run in filename order on every deploy
seed.sql optional — runs on first deploy / fork, once per project
hatchable.toml optional overrides (cron, auth, project name)
package.json dependencies (no build scripts yet — build locally, commit public/)Routing precedence
Most-specific wins. For a request to /api/users/42:
api/users/42.js(static) — beatsapi/users/[id].js(single-param,params.id = "42") — beatsapi/users/[...rest].js(catch-all,params.rest = ["42"])
Catch-all params arrive as string[], never slash-joined. Use req.params.path as an array:
const [first, ...rest] = req.params.path;
Static file resolution (public/)
A request to /foo/bar/baz tries, in order:
public/foo/bar/baz(exact file)public/foo/bar/baz.htmlpublic/foo/bar/baz/index.htmlAncestor
index.htmlfallback — walks up:public/foo/bar/index.html→public/foo/index.html→public/index.html
Step 4 means each folder with an index.html acts as its own mini-site. You can ship
an /admin/* React SPA alongside a static marketing page at / — unmatched paths
under /admin/ fall back to public/admin/index.html, not the root one.
Handler contract
Every file under api/ exports a default async function:
// api/users/list.js
import { db, auth } from "hatchable";
export default async function (req, res) {
const user = auth.getUser(req);
if (!user) return res.status(401).json({ error: "Not logged in" });
const { rows } = await db.query(
"SELECT id, name FROM users WHERE org_id = $1",
[user.id]
);
res.json(rows);
}
// Optional: restrict methods
export const methods = ["GET"];
// Optional: register this endpoint as a recurring scheduled task.
// Minimum interval is hourly. See also: scheduler.at() in the SDK
// for imperative / one-shot / per-firing-payload scheduling.
// export const schedule = "0 */6 * * *";req (Express-shaped)
method, url, path, headers, cookies, params, query
body — parsed by Content-Type: JSON → object, urlencoded → object, multipart/form-data → object of non-file fields
files — present for multipart uploads: [{ field, filename, contentType, buffer }]
res (Express-shaped)
res.json(data), res.status(code) (chainable), res.send(text|buffer)
res.redirect(url), res.cookie(name, value, opts), res.setHeader(name, value)
SDK — import from "hatchable"
Everything you need lives under one import. Do not reach for npm packages
that duplicate these — the deploy linter rejects puppeteer-core,
@anthropic-ai/sdk, pg, nodemailer, bullmq, ioredis,
@aws-sdk/client-s3, child_process, etc. and points you here.
// project storage / SQL
db.query(sql, params) → { rows, rowCount }
db.transaction([{sql, params}, ...]) → { results: [...] }
storage.put(key, buffer, contentType) → url
storage.get(key) → { buffer, contentType }
storage.del(key)
// identity + comms
auth.getUser(req) → { id, email, name } | null
email.send({ to, subject, html })
// scheduling + background work
scheduler.at(when, route, opts?) → declared/armed cron
scheduler.cancel(taskId)
// browser, AI, knowledge — managed services, no npm install
browser.html(url) / browser.pdf(url) / browser.screenshot(url)
browser.session(async page => { ... }) → puppeteer-shaped
ai.generateText({ model: 'sonnet', prompt | messages, system?, tools?, maxSteps?, purpose? })
ai.streamText(opts) → AsyncIterator
ai.embed(input) → { embedding } | { embeddings }
knowledge.base(name, { dimensions }).add/search/searchByVector/remove/table
External HTTP via global fetch (routed through Hatchable's egress
proxy automatically). Project secrets are declared in hatchable.toml
under [[secret]]; humans paste values via the platform-rendered
setup gate. ai.generateText reads keys server-side via the gateway —
never via raw process.env.
What you cannot do
Spawn binaries (no
child_process, no shell).Persist to local filesystem between requests (use
storageinstead).Open a long-lived TCP/WebSocket server.
Install npm packages with native bindings — Hatchable does not run
npm installat deploy. The SDK above replaces every common reason to reach for one.
Scheduling
Two ways to schedule a function — pick based on whether the "when" is known at deploy time or at runtime.
Declared (static, lives in source, reconciled on deploy):
// api/nightly-report.js
export const schedule = "0 9 * * *"; // 5-field cron, minimum hourly
export default async function (req, res) { /* ... */ }Armed (dynamic, from user code, preserved across deploys):
import { scheduler } from "hatchable";
// recurring — first arg is a 5-field cron string
await scheduler.at("0 * * * *", "/api/ping");
// one-shot at a specific moment, with per-firing payload
await scheduler.at("2026-05-01T07:00:00Z", "/api/book", {
payload: { missionId: 42 }
});
// idempotent named arm — repeated calls update the same task
await scheduler.at("0 9 * * *", "/api/digest", { name: "daily-digest" });
// cancel by id
await scheduler.cancel(taskId);Each firing invokes route with req.headers['x-hatchable-trigger'] === 'cron'
and req.body === payload. Use one-shot + payload instead of writing your
own "pending jobs" table with a polling cron — that's the pattern the
primitive replaces.
Database
Postgres. Write schema in migrations/*.sql. Files run in filename order, tracked in __hatchable_migrations so each runs once.
Always use RETURNING to get inserted ids in the same round trip:
INSERT INTO users (email) VALUES ($1) RETURNING idNever call lastval() or LAST_INSERT_ID() — each db.query is a fresh connection, so session-local state doesn't carry across calls.
Available APIs
Functions run in V8 isolates. You get:
The full Hatchable SDK (see above).
Plain JS / TypeScript (no transpile step needed for modern syntax).
fetchfor external HTTP (routed through Hatchable's egress proxy for quota + accounting; pass through transparently to the URL).Web Crypto and standard ECMAScript builtins.
Pure-JS npm packages — anything that doesn't need native bindings, filesystem persistence, child processes, or raw sockets. Common ones used regularly: csv-parse, xlsx, bcrypt, jsonwebtoken, uuid, date-fns, lodash, marked, sanitize-html, cheerio, xml2js, qrcode, stripe.
Declared secrets via
process.env.KEY(only for[[secret]]entries in hatchable.toml that haveexpose = true; the project owner pastes the value through the setup gate). Most secrets are SDK-mediated and never reach process.env — see the secrets docs.
What's NOT available — and the SDK alternative:
You wanted | Use this |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| URL-based storage transforms (planned); |
|
|
| not available — use |
The deploy linter rejects deploys that import the deny-listed packages and points you at the right SDK module by name. You'll see the redirect message before the deploy lands.
Visibility
Three tiers — each one a step up in who the software is for:
personal — free. You and anyone you invite. Login-gated via Hatchable accounts. Build anything including auth — test the full flow with your invitees before going live.
public — $12/mo. On the open web. Custom domains. No branding. No app-level auth (use Hatchable identity only).
app — $39/mo. On the open web + your app has its own users. Email/password signup, OAuth, password reset. If your project has [auth] enabled, this is the only live tier — you can't go Public with auth, you go straight to App.
Calling the API from public/
At deploy time, Hatchable injects a tiny bootstrap into every HTML file:
window.__HATCHABLE__ = { slug: "my-app", api: "/api" };Use it as the base URL:
const API = window.__HATCHABLE__.api;
fetch(API + "/users/list").then(r => r.json()).then(render);Auth (optional)
Enable auth in hatchable.toml to get a complete passwordless login flow with one config block. The platform auto-mounts /api/auth/* — do not write files under api/auth/ when auth is enabled.
[auth]
enabled = true
providers = ["email"]The flow is email-only and passwordless: enter email, receive a 6-digit code, optionally bind a passkey for one-tap returning logins. There are no passwords.
Frontend: every page on a project with [auth] enabled automatically gets window.hatchable.auth — the platform-managed client that wraps every endpoint plus the WebAuthn ceremony. Don't fetch /api/auth/* directly, don't import a WebAuthn library:
const r = await window.hatchable.auth.startLogin({ email });
// r.has_passkey tells the UI whether to offer the passkey button
await window.hatchable.auth.verifyCode({ email, code }); // → { user }
await window.hatchable.auth.signInWithPasskey({ email }); // → { user }
await window.hatchable.auth.registerPasskey(); // post-signin or settings
await window.hatchable.auth.passkeys.list(); // [{ id, name, ... }]
await window.hatchable.auth.passkeys.remove(id);
await window.hatchable.auth.signOut();
await window.hatchable.auth.getSession(); // current session
window.hatchable.auth.supportsPasskeys(); // gate passkey UIServer side, use auth.requireUser / auth.getUser exactly as before. The platform-mounted endpoints (under /api/auth/*) are an implementation detail of window.hatchable.auth — you don't write fetch() calls to them, and you can't put your own files at api/auth/anything.js.
Users live in these tables inside your project's own database: users, sessions, verifications, passkeys
You can extend the users table with your own columns:
-- migrations/002_user_profile.sql
ALTER TABLE users ADD COLUMN phone text;
ALTER TABLE users ADD COLUMN tier text DEFAULT 'free';You CANNOT drop or rename users/sessions/verifications/passkeys or create your own tables with those names — the deploy will fail with a clear error.
In your API functions, use auth.requireUser to gate routes:
import { auth, db } from "hatchable";
export default async function (req, res) {
const user = await auth.requireUser(req, res);
if (!user) return; // requireUser already wrote the 401
const { rows } = await db.query(
"SELECT * FROM bookings WHERE user_id = $1",
[user.id]
);
res.json(rows);
}For the canonical login + passkey UI shapes, read skills auth/enable-app-auth
and auth/register-a-passkey.
Deploy
After writing files, call the deploy tool. It runs migrations, seeds
(first deploy only), copies public/ to the CDN, registers api/ routes,
and — if [auth] enabled — provisions the auth tables in your database.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable project name (e.g. "My Booking App") | |
| visibility | No | Initial project visibility: personal (default, login-gated, free) or public ($12/mo, open web). Cannot be changed via MCP after creation — visibility flips are dashboard-only. | |
| description | No | Short project description |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true, which is consistent with creating a new project. The description adds detail about what is created (slug, database, project ID) but does not discuss side effects like potential resource costs or limits. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely long (over 2000 words) and includes extensive documentation about project structure, routing, SDK, auth, etc. Much of this content is relevant to the project platform but not specific to the create tool. This buries the key purpose and usage guidelines. A concise description (e.g., 5 sentences) would be far more helpful for an agent deciding when to call this tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the large amount of text, the description lacks certain completeness for the tool itself. It does not specify the exact return value shape (e.g., JSON fields returned), error cases (e.g., name conflicts, invalid visibility), or whether the database is immediately accessible. The output schema is absent. The description over-delivers on platform concepts but under-delivers on tool-specific behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the parameters. The description adds value by explaining the free/$12/$39 tiers and that 'personal' is default, but does not elaborate on 'description' beyond the schema. The visibility enum is well explained in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new Hatchable project, generating a URL slug, database, and returning IDs/URLs. It also positions this as the first step before writing files or creating tables, distinguishing it from sibling tools like deploy or write_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this first before writing files or creating tables,' providing clear sequencing. It also implicitly contrasts with update_project (for existing projects) and deploy (for deploying after creation). No explicit alternatives are named, but the context is very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_fileADestructiveIdempotentInspect
Delete a project file. Takes effect after the next deploy.
Optional reason: surfaces in the History view so the user understands why the file was removed.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path to delete | |
| reason | No | Optional. Short note (≤ 1000 chars) about why this file is being removed. | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=true, so the description doesn't need to repeat those. The description adds critical behavioral context: 'Takes effect after the next deploy' which is beyond annotations. This clarifies that deletion is not immediate, which is essential for agent understanding. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, zero wasted words. It states the action and a crucial deferred effect. Perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema), the description is adequate but not complete. It misses mention of whether deletion is reversible, any prerequisites (e.g., file must exist), and the exact behavior after deploy (e.g., do you get a confirmation?). However, with good annotations and full schema coverage, it's minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description does not add any extra meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'delete' and resource 'project file', and adds the important qualifier 'Takes effect after the next deploy' which distinguishes it from immediate deletion. This is clear but doesn't explicitly contrast with sibling tools like write_file or patch_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting a file, but provides no guidance on when not to use it or alternatives. For example, it doesn't mention that deleted files might be recoverable or that 'deploy' must be called for the deletion to take effect, nor does it contrast with tools like write_file that might overwrite or modify files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
deployDeploy projectADestructiveInspect
Deploy the project. Runs migrations/*.sql (tracked so each runs once), runs seed.sql on first deploy, copies public/ files to the CDN, and registers api/ files as live endpoints. Increments the project version.
Always populate intent and summary so the user sees a readable changelog in the console:
intentis what the USER asked for, in their own words. Quote or lightly paraphrase their last instruction. e.g. "Add a split-the-bill section", "Make the buttons rounder".summaryis what YOU did, in plain language they can read. 1–3 sentences. e.g. "Added a SplitBill component with a member counter and per-person breakdown. Updated the main page nav to switch between solo and split modes."
These become the commit message AND the History row title in the console. A user will likely scroll their History a week from now to remember what they built — write the summary so a future-you-with-no-context understands what shipped. If there is no clear user prompt (autonomous maintenance), leave intent blank but still pass a summary describing what changed and why.
Call this after writing all your files. To verify your functions work after deploying, use run_function — it calls the function directly through your authenticated session and works for all project visibilities. The url field is the public URL for end users — personal projects require visitors to sign up before they can view the site.
| Name | Required | Description | Default |
|---|---|---|---|
| intent | No | What the user asked for, in their own words (≤ 500 chars). e.g. "Add a split-the-bill section". Leave blank only for autonomous agent maintenance with no prompting user. | |
| summary | No | Plain-language description of what you did and why. 1–3 sentences. Reads as the changelog entry. e.g. "Added a SplitBill component with a member counter; updated the nav to toggle between solo and split modes." | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, so the mutation is known. The description adds details about what it does (migrations, seeds, CDN, endpoints, version increment) and mentions side effects like first-deploy seed and personal project restrictions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with actions, but the last sentence about url field is somewhat tangential to the deploy action. Still efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains what happens and when to use. It covers key behavioral aspects. Could mention that it's not idempotent (but annotations already provide destructiveHint). Overall sufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of project_id. The description adds context about deployment behavior but no additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Deploy' and the resource 'project', and lists specific actions: runs migrations, seeds, copies files, increments version. It also distinguishes from the sibling 'dry_run_deploy' by being the actual deploy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this after writing all your files', and provides alternatives: 'To verify your functions work after deploying, use `run_function`'. Also distinguishes between public URL and personal project behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
dry_run_deployARead-onlyInspect
Run every deploy-time validator against the project's current files without actually deploying. Returns errors (hard gates) and warnings (soft lints), plus a would_deploy summary of what would ship.
Errors catch: package.json build scripts, reserved table names in migrations, auth route collisions, usage cap breaches.
Warnings catch known runtime footguns that type-check but silently misbehave — most notably auth.getUser() / auth.getSession() / db.query() calls without await (returning a Promise is truthy, so if (!user) guards pass and downstream user.id is undefined). Safer than calling deploy blindly and finding out mid-flight.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing specific error/warning checks and the 'would_deploy' summary. It mentions runtime footguns (e.g., missing await) but could further clarify side effects or scope of validation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs: first states purpose and return values, second lists specific checks. Every sentence adds value without redundancy, and it is appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (one parameter) and clear annotations, the description is complete enough. It explains the output structure and examples of errors/warnings. No output schema exists, but the description compensates by listing return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the 'project_id' parameter is fully described in the schema. The description does not add extra semantics for this parameter, earning a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs validators without deploying, distinguishing it from the 'deploy' sibling. It lists specific checks (package.json, reserved table names, auth routes, usage caps) and return types (errors, warnings, would_deploy), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use before deploying to avoid mid-flight failures, and contrasts with 'deploy' by mentioning safety. However, it does not explicitly state when not to use this tool (e.g., when no validators exist) or alternatives beyond deploying.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
execute_sqlADestructiveInspect
Run SQL against the project's dedicated PostgreSQL database.
Supports: CREATE TABLE, ALTER TABLE, DROP TABLE, INSERT, SELECT, UPDATE, DELETE.
Use parameterized queries for safety: pass values in the params array with $1, $2, etc. placeholders.
Return format:
SELECT: { rows: [...], count: N } — DECIMAL columns return as strings (e.g. "45.00")
INSERT/UPDATE/DELETE: { changes: N }
DDL: { changes: 0 }
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL statement to execute | |
| params | No | Bind parameters (use $1, $2, etc. placeholders in SQL) | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark the tool as destructiveHint=true, which is consistent with SQL mutations. The description adds behavioral details: return formats for different SQL types, and that DECIMAL columns return as strings. With no output schema, this is valuable transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections: supported statements, parameterized query guidance, and return format examples. It's concise and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description compensates by detailing return formats. It explains supported SQL types and behavior for different statements. Missing information about error handling or permissions, but overall complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by explaining the binding pattern ($1, $2) and encourages parameterized queries for safety, which is not in schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs SQL against the project's PostgreSQL database, listing supported DML and DDL statements. It distinguishes itself from siblings like run_code or run_function which run code, not SQL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidelines by encouraging parameterized queries and specifying placeholders ($1, $2). It also hints at proper usage by mentioning safety, but does not explicitly say when not to use this tool vs alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fork_projectAInspect
Fork a public project into your account. Copies all code and database schema (no data). The fork starts as a personal project you can modify freely.
This is the recommended way to start from an existing app: fork it, then modify the code.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional new name for the fork (defaults to source name) | |
| project_id | Yes | Project ID of the public project to fork |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show destructiveHint=false, readOnlyHint=false. The description clarifies it copies code and schema but no data, and the fork becomes a personal project. This adds behavioral detail beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary action, and each sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema, clear annotations, and no output schema needed, the description fully covers what an agent needs: action, scope, constraints, and recommendation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters. The description adds no additional meaning beyond the schema descriptions (overall purpose, defaults) for 'name' and 'project_id', so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fork a public project into your account') and what is copied ('code and database schema without data'). It distinguishes from siblings like 'create_project' by specifying it starts from an existing app, but does not explicitly differentiate from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends when to use this tool: 'This is the recommended way to start from an existing app' and implies use before modification, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_deploymentARead-onlyInspect
Detail view of one deployment by version number — returns the full file manifest (paths, hashes, sizes) and function list captured when that version shipped. Use it with list_deployments to audit or compare what changed between versions.
| Name | Required | Description | Default |
|---|---|---|---|
| version | Yes | Deployment version number | |
| project_id | Yes | Project ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by detailing return contents (file manifest, function list) and hinting at historical capture behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and every sentence adds value. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, schema coverage, and annotations, the description is largely complete. It could mention pagination or limits on file manifest size, but the current level is sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so schema already describes both parameters. Description does not add extra meaning beyond the schema, earning a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Detail view of one deployment by version number' and specifies what it returns: 'full file manifest (paths, hashes, sizes) and function list'. It distinguishes from siblings like list_deployments by noting it gives detail for a specific version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description suggests using it with list_deployments to audit or compare versions, providing clear context. However, it does not explicitly state when not to use it or list alternatives beyond list_deployments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_projectARead-onlyInspect
Get project details including slug, visibility, status, deployed functions, and the database schema (tables, columns, types).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, confirming it's a safe read. The description adds value by specifying what information is returned (database schema, deployed functions), going beyond the annotation signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that efficiently lists the key details returned, with no superfluous words. Perfectly sized for a focused retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one string ID) and no output schema, the description adequately covers what is returned. The lack of output schema is acceptable as the description lists the types of data included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (only one parameter), and its description in the schema is clear. The description adds no new parameter-level info beyond what the schema provides, earning the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifically states 'Get project details' and lists exact fields (slug, visibility, status, deployed functions, database schema), clearly distinguishing it from siblings like 'list_projects' or 'get_schema'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it should be used when full project details are needed, but does not explicitly mention when not to use it or alternatives. For example, if only the schema is needed, 'get_schema' might be more appropriate, but this is not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_schemaARead-onlyInspect
Return the database schema for the project's PostgreSQL database: tables, columns (with types), and indexes.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds context about the output content (tables, columns, indexes), which is helpful beyond annotations. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the purpose and output. No extraneous words, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a read-only retrieval tool with one parameter and no output schema. It covers the main output aspects (tables, columns, types, indexes). A minor gap is that it doesn't specify if the schema is for the entire project or specific parts, but the context (project_id) implies project-wide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with a single required parameter (project_id). The description does not elaborate on the parameter beyond what the schema provides, but the schema is already clear. Therefore, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns database schema including tables, columns with types, and indexes. It specifies the resource (PostgreSQL database schema) and verb (return), and is distinct from siblings like execute_sql or run_function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining schema details but provides no guidance on when to use this versus alternative tools (e.g., execute_sql for running queries). No exclusions or special conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grepARead-onlyInspect
Regex content search across a project's files. Postgres-backed, scoped to one project, with glob filtering.
Three output modes:
files_with_matches (default) — list paths containing a match
content — matching lines with optional context and line numbers
count — per-file match counts + total
Default head_limit is 250 to prevent context blowups on broad patterns. Use glob to narrow by path (e.g. 'api//*.js', 'public//.html'). Regex uses Postgres syntax (~ / ~). Invalid or catastrophic patterns error out via a 2s statement timeout — simplify the pattern if that happens.
| Name | Required | Description | Default |
|---|---|---|---|
| -i | No | Case-insensitive match | |
| -n | No | Show line numbers in content mode (default true) | |
| glob | No | Path filter glob (e.g. 'api/**/*.js', 'public/*.html') | |
| context | No | Lines of context before/after each match (content mode) | |
| pattern | Yes | Regex pattern to search for | |
| head_limit | No | Max results to return (default 250, max 1000) | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) | |
| output_mode | No | Output format |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description doesn't need to restate non-destructive behavior. It adds behavior details: Postgres backend, defaults (head_limit=250), error behavior (2s timeout), and glob support. Minus one point because it doesn't clarify whether result ordering is deterministic or mention any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary sentence followed by bullet points (rendered as a list in plain text). It is front-loaded with the core purpose. Slightly long but each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, 3 output modes) and no output schema, the description covers the major behavioral aspects and defaults. It could mention that output is not sorted or explain the Postgres regex syntax more, but it's sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description can be brief on params. It adds value by explaining output modes and default head_limit, but doesn't elaborate beyond the schema for each parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs regex content search across project files, with specific verb 'search' and resource 'project files'. It distinguishes itself from sibling tools like 'search_documentation' or 'search_projects' by focusing on file content and specifying the regex backend and scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool, including the three output modes, head_limit for broad patterns, glob filtering for narrowing paths, and how to handle regex errors. It implies it's for file search vs. other search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
import_file_from_urlADestructiveIdempotentInspect
Fetch a remote URL and save the response body as a project file — server-side, so the bytes never pass through your context window. Useful for seed data, vendor libs, and asset migration.
Capped at 10 MB and 10s timeout. Private/loopback addresses are rejected. Path must live under public/, api/, or migrations/, or be one of seed.sql / hatchable.toml / package.json.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full http(s) URL to fetch | |
| path | Yes | Destination path in the project | |
| project_id | Yes | Project ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include 'destructiveHint: true' and 'idempotentHint: true', but the description adds valuable behavioral details: the file is created server-side, bytes never pass through context, has size and timeout limits, and rejects private addresses. It also specifies allowed paths, which is critical for understanding side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and front-loaded with the primary action and benefit. Every sentence adds necessary information: purpose, use cases, and constraints. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, no output schema, but with constraints), the description fully covers what the tool does, its boundaries (size, timeout, network restrictions), and allowed paths. It is complete for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all three parameters with descriptions, but the description adds context that 'url' is a remote URL to fetch, 'path' is a destination path with constraints (must be under specific directories), and 'project_id' is for project identification. Since schema coverage is 100%, baseline is 3; the description adds extra value about path restrictions, raising the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch a remote URL and save the response body as a project file' with the specific verb 'Fetch' and resource 'remote URL' and 'project file'. It distinguishes itself from siblings like 'upload_file' or 'write_file' by mentioning server-side fetching and avoiding the context window.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions use cases ('seed data, vendor libs, and asset migration') and constraints ('Capped at 10 MB and 10s timeout', 'Private/loopback addresses are rejected', 'Path must live under...'). However, it does not explicitly state when NOT to use this tool versus alternatives like 'write_file' or 'upload_file'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_cron_jobsARead-onlyInspect
List every scheduled task for a project. A task points at a function and carries a cron expression (recurring) or a one-shot fire_at, plus an optional payload delivered as the request body. Tasks are either 'declared' (written into source via export const schedule or hatchable.toml, reconciled on deploy) or 'armed' (inserted by the SDK scheduler.at() call, preserved across deploys). Response includes next_fire_at, last_fired_at, attempts, last_error, and 7-day run/error counts from FunctionLog. Diagnostic: if next_fire_at keeps moving forward but last_fired_at never advances, the scheduler isn't running.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as readOnlyHint=true and destructiveHint=false. The description adds value by specifying the data returned (7-day run count, error count, last_run_at) and the context (scheduled functions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states what it does, second gives a specific use case. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple input (single required param), no output schema, and good annotations, the description is complete. It explains the output fields and typical usage. Slight lack of detail on expected output format (e.g., is it a list? what if empty?).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter project_id. The description doesn't elaborate on the parameter, but the schema is minimal and clear. The description adds value by explaining what the tool returns, which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists cron jobs with specific fields (cron expression, run count, error count, timestamp), which is specific and differentiates from siblings like list_functions or list_deployments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this to verify cron jobs are firing without tailing logs, providing a clear use case. However, it doesn't mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_deploymentsARead-onlyInspect
List deployments for a project in reverse-chronological order. Each entry includes version, status, deployed_at, description, and summary counts (files, functions).
Use this to understand recent deploy history, identify a known-good version for rollback, or debug a regression by comparing two versions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max deployments to return (default 20, max 100) | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, which covers non-destructive behavior. Description adds ordering and included summary counts, which are useful but not critical. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs: first explains what and how, second explains why. No unnecessary words. Could be slightly tighter, but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with 2 parameters, the description covers purpose, output fields, ordering, and use cases. Lacks pagination behavior beyond limit, but sufficiently complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters (limit, project_id). Description does not add parameter-specific meaning beyond schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states specific action (list deployments), resource (project), ordering (reverse-chronological), and included fields (version, status, etc.). Clearly distinguishes from sibling tools like get_deployment which retrieves a single deployment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly suggests use cases: understand deploy history, identify known-good version for rollback, debug regression. Lacks explicit when-not-to-use or alternatives for similar purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_filesBRead-onlyInspect
List all files in a project with their paths, sizes, and hashes.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, so the description adds little beyond confirming read-only. It does not mention performance or pagination, which might be relevant for large projects. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and front-loaded. Could be slightly more structured (e.g., bullet points), but adequate for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and annotations are minimal, the description provides basic output info (paths, sizes, hashes) but misses return format details, pagination, and sorting behavior. Adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (one parameter with description). The description does not add extra meaning beyond the schema's description of project_id. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists files in a project and mentions the output fields (paths, sizes, hashes). It distinguishes from siblings like get_project (project-level) and read_file (single file). However, it could be more specific about which files (e.g., all files recursively?).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, when to use list_files over grep or read_file. No explicit context about prerequisites (e.g., project must exist).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_functionsARead-onlyInspect
List every deployed API function for a project: route, method, runtime tier, type ('scheduled' if the function has at least one active scheduled task, else 'api'), and 24-hour invocation and error counts.
This is the 'what routes did I ship' introspection tool. Call it after a fork, after picking up an unfamiliar project, or to verify a deploy registered the endpoints you expected. Much cheaper than reading every api/ file with read_file. For scheduling details (cron, fire_at, payload, run history) use list_cron_jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds that it is an 'introspection tool' and discloses the returned data cost (cheaper than reading files). No behavioral contradictions, but could mention if it requires specific permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first explains what it does and returns, second gives usage context. No fluff, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description helpfully lists returned fields (route, method, etc.) which is sufficient for an introspection tool. Could mention pagination or filtering, but the simplicity and annotations make it complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the single required parameter (project_id) with description. The description does not add extra parameter semantics beyond the schema, earning a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists 'every deployed API function for a project' and enumerates specific fields returned (route, method, runtime tier, cron schedule, invocation/error counts). It differentiates from siblings like list_deployments and list_files by focusing on functions, and from read_file by being cheaper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'after a fork, after picking up an unfamiliar project, or to verify a deploy registered the endpoints you expected.' It also contrasts with read_file as 'much cheaper,' guiding the agent to prefer this over alternatives for overview purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_pending_uploadsARead-onlyInspect
Show multipart uploads currently staged for this project that haven't yet been committed. Use this to recover from a disconnect — find the upload_id and resume from the next chunk_index. Uploads expire 10 minutes after the last chunk was added.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by disclosing an expiration behavior ('Uploads expire 10 minutes after the last chunk was added'), which is critical for understanding data staleness. Would be a 5 if it also explained pagination or maximum list size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states the purpose, second gives usage scenario, third conveys an important behavioral detail. Each sentence serves a distinct purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema), the description covers the key aspects: what it does, when to use it, and a time-bound behavior. Minor omission: no mention of how to commit the upload (but that might be another tool's job).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage and only 1 parameter, the schema already documents 'project_id' as a string. The description does not add extra meaning or constraints for the parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Show') and resource ('multipart uploads currently staged for this project that haven't yet been committed'). It clearly distinguishes from sibling operations like 'upload_file' by focusing on pending/uncommitted uploads rather than initiating new ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('recover from a disconnect') and how to proceed ('find the upload_id and resume from the next chunk_index'). This provides actionable guidance beyond the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_projectsARead-onlyInspect
List all projects you own or collaborate on, with their visibility, tier, role, and current version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds value by listing returned fields (visibility, tier, role, version), which goes beyond annotations, but does not disclose pagination or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no waste, front-loaded with verb and resource. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 0 parameters, no output schema, and clear annotations, the description is nearly complete. It could mention that it returns a list, but that is implied by 'list'. The returned fields are specified, which suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters, so description cannot add parameter meaning beyond what schema provides. Schema coverage is 100%, making a baseline score of 4 appropriate, but since there are no parameters to explain, a 3 is reasonable for neutral impact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('list') and resource ('projects you own or collaborate on'), and distinguishes what properties are returned (visibility, tier, role, current version). This differentiates it from sibling tools like 'search_projects' which likely involve filters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving all projects you are involved in, with no explicit when-not or alternatives. However, given the sibling 'search_projects', it contrasts by not offering search capabilities, which is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_skillsARead-onlyInspect
List the registry of platform skills — discrete how-to guides for one specific task each (e.g. 'gate-an-endpoint', 'add-a-cron-job', 'add-rag-search'). Each entry is a name, one-line purpose, and category. Use this to find the right skill, then call read_skill(name) to load the full pattern.
When in doubt about how a Hatchable feature works, list_skills first. The skills are the canonical, agent-tested patterns. They beat guessing or reading the verbose docs.
Filter by query (matches name + purpose) or tag (auth, data, ai, ops, etc.). Without filters, returns the full registry (~35 entries).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Optional category filter: auth | data | pages | api | background | ai | email | browser | ops | project | |
| model | No | Optional. Your model identifier (e.g. "claude-opus-4-7", "claude-sonnet-4-6", "gpt-5", "gemini-2.5-pro"). Hatchable uses this to tune skill content to your model — terser variants for stronger reasoners, more explicit next-step cues and anti-pattern callouts for smaller ones. Declare once per session; we remember it for subsequent skill reads. | |
| query | No | Optional substring filter against name and purpose (e.g. "send email", "fork", "rag") |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description adds value by describing the return format (name, purpose, category) and the behavior when no filters are applied (full registry of ~35 entries).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: first paragraph defines the tool and its relation to `read_skill`, second paragraph gives filtering details. It is concise, though the second sentence could be tightened slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description fully describes the return values (name, purpose, category) and the registry size (~35). This provides sufficient context for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have complete schema descriptions. The description adds context: `query` matches name+purpose, `tag` is a category filter with listed options, and explains behavior without filters. This goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing platform skills (discrete how-to guides) and distinguishes it from the sibling `read_skill` by specifying this tool returns the registry for finding the right skill.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this to find the right skill, then call `read_skill(name)`' and 'When in doubt... list_skills first'. This tells the agent both when to use it and what to use after.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
patch_fileADestructiveInspect
Apply a targeted edit to an existing project file without rewriting the entire file. Finds the first occurrence of old_string and replaces it with new_string. Use this instead of write_file when modifying large files (e.g. HTML) — you only send the changed portion, not the whole file.
The old_string must match exactly (including whitespace). If it's not found, the tool returns an error. To insert at a specific position, use a nearby string as old_string and include it in new_string with your addition.
Optional reason: short note about why this patch — surfaces in the console's History view next to the file's diff. Include when the patch's purpose diverges from the deploy's overall intent.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to project root | |
| reason | No | Optional. Short note (≤ 1000 chars) about why this particular patch. | |
| new_string | Yes | Replacement string | |
| old_string | Yes | Exact string to find and replace | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is destructive (matches annotation `destructiveHint: true`) and explains the replacement logic and error condition. It adds context beyond annotations by specifying that only the first occurrence is replaced and that the old_string must match exactly. Slightly lower score because it does not mention whether the operation is idempotent (though annotation says false) or if there are side effects like file locking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each adding essential value: purpose and comparison to write_file, usage guidelines with exact match requirement, and insertion technique. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (4 parameters, no output schema), the description covers most necessary context: when to use, how it works, error condition, and insertion trick. Minor gap: no mention of encoding or file size limits, but that is acceptable for a straightforward edit operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds context about exact match requirement and insertion technique but does not provide additional semantic meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Patch file') and resource ('existing project file'), and clearly states that it replaces the first occurrence of `old_string` with `new_string`. It distinguishes itself from the sibling `write_file` by noting it is intended for targeted edits without rewriting the entire file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('instead of write_file when modifying large files') and provides guidance on how to insert at a specific position. It also warns about the requirement for exact match and error behavior, giving clear context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_fileARead-onlyInspect
Read the content of a project file.
Pass offset/limit to read a range of lines — useful for large files where the whole file would blow the context window. When either is set, the response includes cat -n style line-numbered content so subsequent patch_file calls can reference exact line numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to project root | |
| limit | No | Max number of lines to return. Omit to read to end. | |
| offset | No | Starting line number (1-indexed). Omit to read from start. | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint true, so no destructive behavior. Description adds that offset/limit return line-numbered content for patch_file, which is useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with purpose, then usage. Could be slightly more concise, but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple read operation and full schema coverage, description is complete. No output schema needed since return is just file content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes all 4 parameters clearly (100% coverage). Description adds context about line numbers for offset/limit but doesn't add meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads a project file, distinguishes from siblings like write_file, patch_file, and grep. Specific verb+resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides when to use offset/limit (for large files), but doesn't explicitly mention when not to use this tool or alternatives like grep for content search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_skillARead-onlyInspect
Load the full markdown body of one skill: when to use it, the canonical code shape, common pitfalls, and how to verify it works. Skills are the platform's primary agent-facing reference — every pattern an agent might need is one of these.
Pass either the bare name (e.g. 'gate-an-endpoint') or the category-qualified path (e.g. 'auth/gate-an-endpoint'). Use list_skills first to discover names.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Skill name from list_skills (e.g. "gate-an-endpoint" or "auth/gate-an-endpoint") | |
| model | No | Optional. Your model identifier (e.g. "claude-opus-4-7", "claude-sonnet-4-6", "gpt-5", "gemini-2.5-pro"). Hatchable uses this to tune skill content to your model — terser variants for stronger reasoners, more explicit next-step cues and anti-pattern callouts for smaller ones. Declare once per session; we remember it for subsequent skill reads. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds context about the content of skills (use cases, code shape, pitfalls, verification). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a usage hint. No fluff, key information front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with 1 param and no output schema. Description covers purpose, usage, parameter options, and prerequisite. Fully complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema describes the parameter. Description adds value by mentioning two formats and hinting at list_skills, but does not significantly extend beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Load the full markdown body of one skill' with specific verb and resource. It distinguishes from siblings by advising to use list_skills first.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear guidance on when to use (skills as primary agent-facing reference) and how to pass the name (bare or qualified). Explicitly tells to use list_skills first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_codeADestructiveInspect
Execute arbitrary JS in the project's isolate runtime. The SDK is pre-imported into local scope — db, auth, email, storage, ai, agent, cache, knowledge, memory, tasks, scheduler, browser, run, approval are ready to use without import. process.env and global fetch also work. return to produce the result field. Top-level import and dynamic import('hatchable') are NOT supported in this REPL — the bindings above are how you reach the SDK.
Use this as a REPL: probe the database, verify a computation, test an API shape before committing it to a file. Nothing is persisted — the snippet runs once and disappears.
Caps: 5s default timeout (max 30s), 256 KB max source length.
Example:
run_code({ project_id, code: const { rows } = await db.query("SELECT count(*) FROM users");
return rows[0];
})
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | JS snippet. Use `return` to produce a result. | |
| project_id | Yes | Project ID | |
| timeout_ms | No | Execution timeout in ms (default 5000, max 30000) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details runtime environment (same bindings, non-persistent), but the destructiveHint annotation already indicates potential side effects (e.g., database writes). The description adds value by clarifying scoping (isolate runtime), timeout, and source length caps, and that nothing is persisted. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with front-loaded purpose, clear guidelines, caps, and an example. Every sentence adds value, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains return value ('result' field) and provides context about environment, caps, and example. It is complete for understanding the tool's behavior and constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions. The description adds context beyond schema: code snippet environment and return behavior, timeout range, and an example. However, the example is redundant with the param description for 'code'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes arbitrary JS in an isolate runtime with specific bindings, distinct from siblings like run_function or execute_sql. It uses a specific verb (Execute) and resource (JS in isolate runtime with bound APIs), leaving no ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this as a REPL for probing, verifying, testing, and notes that nothing is persisted. It implicitly differentiates from siblings like run_function (deployed functions) and write_file (persistence), and sets clear expectations for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_functionADestructiveInspect
Execute a deployed function and return the real response. Use this to test your API endpoints.
Returns: { status, headers, body, logs, error, duration_ms }
Example: run_function({ project_id: 1, path: "/api/users", method: "GET" }) Example: run_function({ project_id: 1, path: "/api/users", method: "POST", body: { name: "Alice" } })
IMPORTANT: Always run_function on your API endpoints after writing them. Inspect the response body field names and types. Then write your frontend to match those exact names.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body (for POST/PUT) | |
| path | Yes | Function route path (e.g. "/api/services") | |
| query | No | URL query parameters | |
| method | No | HTTP method | |
| headers | No | Additional request headers | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true and openWorldHint: true, which are well-addressed by the description (executing a function). The description adds return structure and example usage, but does not elaborate beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: three sections in two paragraphs. Front-loaded with purpose, then returns, then examples, then best-practice callout. Slightly verbose in the last sentence, but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is medium complexity with 6 parameters. Without an output schema, the description does well to list the return object. However, it could mention error handling or rate limits, but the examples partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra parameter-level details beyond examples; the schema already describes each parameter sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool executes a deployed function and returns the real response, with a clear verb ('Execute') and resource ('deployed function'). The sibling tools include 'list_functions' and 'deploy', so 'run_function' is unambiguously distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Use this to test your API endpoints' and 'Always run_function on your API endpoints after writing them.' No alternatives are needed among siblings; this is the unique tool for testing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_documentationARead-onlyInspect
Search Hatchable's own documentation for platform behavior — routing, the SDK surface, deploy semantics, auth config, runtime limits. Call this instead of guessing when you're unsure how a Hatchable feature works.
Ranks results by term frequency across headed sections. Returns source file, section heading, and a snippet around the hit.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 5, max 20) | |
| query | Yes | Search terms |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds behavioral details beyond annotations: it explains how results are ranked ('by term frequency across headed sections') and what is returned ('source file, section heading, and a snippet'). This helps the agent understand the search mechanics and result format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short paragraphs. The first paragraph states purpose and usage guidance. The second paragraph explains behavior. Every sentence adds value. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple search with two parameters), the description is complete. Annotations cover safety. The description covers purpose, when to use, ranking behavior, and return format. No output schema exists, but the description explains what is returned (source file, section heading, snippet), which is sufficient for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not directly describe parameters, but it adds value by explaining the ranking method and result structure, which helps the agent infer how 'query' will be interpreted. The 'limit' parameter is already described in the schema. The description compensates slightly by providing context on result format, but does not elaborate on parameters beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('Hatchable's own documentation'), and clearly distinguishes the tool's purpose from sibling tools by explaining what topics it covers (routing, SDK, deploy semantics, etc.). It explicitly contrasts with guessing, making the tool's scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: 'Call this instead of guessing when you're unsure how a Hatchable feature works.' This provides clear guidance on when the tool is appropriate and implicitly when not (e.g., for non-Hatchable documentation). No alternative tools named, but the list of sibling tools includes general search (grep, search_projects) and the description positions this as the specific search for platform docs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_projectsARead-onlyInspect
Search the public Hatchable project directory — other people's projects that you can view or fork. Use this to find existing apps to fork-and-modify as a starting point.
Note: this searches the public marketplace. To search inside your own project's files, use the grep tool instead.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20, max 50) | |
| query | No | Search query (matches name, tagline, description) | |
| category | No | Filter by category |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so description does not need to restate safety. Description adds value by clarifying the scope (public marketplace) and note about searching own files. No contradictions. A 4 reflects rich contextual addition beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two clear sentences, front-loading the main purpose. Could be slightly more compact but no redundant information. Loses a point for not being maximally dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (3 optional parameters, no output schema), description fully covers purpose, scope, and usage boundaries. No additional information needed for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are well-documented. Description does not add extra meaning to parameters (e.g., format of query, allowed categories). Baseline 3 is appropriate since schema covers all details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it searches the public Hatchable project directory for other people's projects, contrasting with internal project search using grep. The verb 'search' and resource 'public project directory' are specific and distinct from sibling tools like search_documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use (find existing apps to fork) and when not to use (for internal project files, use grep instead). Provides clear context for choosing this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
setup_accountADestructiveInspect
Associate an email and handle with your account.
Step 1: Call with just email — sends a 6-digit verification code. Step 2: Call with email + code + handle — verifies and completes setup.
This lets you log in to the console and sets your permanent @handle.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Six-digit verification code from email (omit to request a code) | |
| Yes | Email address | ||
| handle | No | Desired @handle (3-30 chars, lowercase, starts with letter) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, which is consistent with account modification. The description adds behavioral context: sending verification code, two-step process, and permanent handle. However, it does not disclose if setup can be undone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: three sentences effectively convey purpose, usage steps, and outcome. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explains what happens (code sent, verification completed, permanent handle set). Could mention that setup is irreversible or session-related details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description supplements it by explaining the role of each parameter in the multi-step flow (e.g., omitting code to request a code). The handle validation (3-30 chars, lowercase, starts with letter) is only in schema, but description adds context about completion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: associate an email and handle with your account, with a step-by-step process for requesting and verifying a code. It distinguishes from sibling tools as no other tool relates to account setup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines a two-step usage pattern: first call with only email, then second call with email, code, and handle. It also states the purpose of the setup (logging in, setting permanent handle). No alternatives needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
submit_platform_feedbackAInspect
Tell the Hatchable team about a platform footgun, friction point, or surprising behavior you hit during this build. Reports go straight into the platform's triage queue and turn into bug fixes, doc updates, or explicit decisions.
When to call: any time a platform constraint, undocumented limit, misleading error, missing helper, or stale doc cost you more than ~5 minutes to figure out — OR any time you successfully reach for a non-obvious workaround that future builds shouldn't have to rediscover. Calling mid-build (right after the workaround) is more useful than at the end of the build, because the painful details are still fresh.
Report quality matters: the title should be one sentence ("TextDecoder caps decoded strings at 32 KB per decode() call"). The body should describe what you tried, the error you got, and the workaround. Reports become Github issues / docs PRs verbatim — write for the engineer who'll fix it, not for yourself.
Don't use this for: generic praise, app-level bugs in the user's own code, anything that's already documented (search skills first via list_skills).
| Name | Required | Description | Default |
|---|---|---|---|
| area | Yes | Bucket: isolate | sdk | gateway | scheduler | storage | browser | ai | mcp | docs | dry-run | console | other. | |
| body | Yes | Long form: what you were trying to do, what you tried, the error, the workaround. The fix-it engineer should be able to reproduce from this. | |
| title | Yes | One-sentence headline. ("Buffer.writeUInt32LE not implemented in isolate" — not "Buffer issue".) | |
| severity | Yes | blocker = cost ~hours to diagnose / silently broke a deploy. friction = cost ~30 min, had a workaround. polish = ~10 min, ergonomics nit. | |
| project_id | No | Optional project this feedback came from. Helps us reproduce against the same code. | |
| agent_model | No | Optional model identifier (e.g. 'claude-opus-4-7', 'claude-sonnet-4-6'). Helps spot model-specific failure patterns. | |
| what_worked | No | Optional. A platform feature or pattern that worked unusually well in this build. Helps us avoid breaking things that aren't broken. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=false, readOnlyHint=false), the description discloses that reports go into the triage queue and become GitHub issues/docs PRs. It also highlights the importance of fresh details, adding behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections ('When to call', 'Report quality matters', 'Don't use this for'), but it is slightly lengthy. Still, every sentence adds value and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (4 required) and no output schema, the description covers usage, report quality, and exclusions. It lacks details on submission confirmation or response, but overall is complete for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value with examples for title format and body content, and explains severity levels (blocker, friction, polish) with concrete costs, enhancing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific language: 'Tell the Hatchable team about a platform footgun, friction point, or surprising behavior.' It clearly identifies the resource (platform feedback) and action (submit), and the example distinguishes it from sibling tools like list_skills.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to call' section provides explicit conditions (cost >5 min, non-obvious workaround) and the 'Don't use this for' section lists exclusions. It also suggests calling mid-build for freshness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_projectADestructiveIdempotentInspect
Update project metadata: name, tagline, description, category, is_template. Only the fields you pass are touched. Slug, tier, and visibility are immutable from MCP — visibility changes are dashboard-only because they can expose data to the open web and may trigger plan upgrades; direct the operator to /console/projects/{slug}/settings.
Setting is_template: true lists the project in the public Templates gallery so other users can fork it. Requires the project to already be public — if it isn't, ask the operator to flip visibility from the dashboard first.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Project name (max 100 chars) | |
| tagline | No | Short tagline (max 200 chars) | |
| category | No | Category label (max 50 chars) | |
| project_id | Yes | Project ID | |
| description | No | Long description (max 2000 chars) | |
| is_template | No | List in the Templates gallery (true) or remove (false). Works on any visibility — gallery shows metadata regardless, and the live preview URL bounces anonymous visitors through login if the project is personal. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Disclosures beyond annotations: mentions that only passed fields are touched (partial update behavior) and that slug and tier are immutable. Annotations already indicate destructiveHint=true (mutation) and idempotentHint=true, which aligns with the 'only fields you pass are touched' behavior. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficient and front-loaded with the verb 'Update' and resource 'project metadata'. Every clause adds value: what can be updated, partial update behavior, which tool to use for visibility, and immutability of slug/tier. Could be slightly more concise but well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (all described in schema), annotations providing mutation and idempotency info, and no output schema, the description covers purpose, partial update behavior, and boundaries (visibility via set_visibility, immutable slug/tier). Missing details like required permissions or error conditions, but acceptable for a metadata update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds value by summarizing which fields can be updated (name, tagline, description, category) but doesn't add additional constraints like limits (max chars) already in schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it updates project metadata and enumerates specific fields (name, tagline, description, category). Distinguishes from sibling tool set_visibility by noting that visibility changes should use that tool instead. Also mentions immutability of slug and tier, adding further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (for updating metadata fields) and when not to use it (for visibility changes, use set_visibility; slug and tier are immutable). This provides clear guidance and directs the agent to alternative tools, making the decision straightforward.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
upload_fileADestructiveIdempotentInspect
Multipart file upload for content that exceeds a single model response's output token cap (big SPA bundles, large seed data, inline vendor libs).
Flow: first call with chunk_index=0 and NO upload_id — response returns an upload_id. Subsequent calls pass that upload_id with chunk_index=1, 2, 3…. Last call sets final=true to atomically concatenate and commit as one ProjectFile.
Chunks are staged in Redis with a 10-minute TTL. chunk_index overwrites (safe to retry). Max chunk size: 64 KB. Max assembled file: 20 MB.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Destination path | |
| chunk | Yes | Chunk content (max 64 KB) | |
| final | No | Set true on the last chunk to commit | |
| upload_id | No | Returned from the first call. Omit for chunk 0. | |
| project_id | Yes | Project ID | |
| chunk_index | Yes | 0-based chunk ordinal |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true (file creation/modification) and idempotentHint=true (safe retries). The description adds details: chunk TTL (10 min), max chunk size (64 KB), max assembly (20 MB), and overwrite safety, which go beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with three sentences: first states purpose, second details flow, third adds constraints. Every sentence is necessary and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description answers key questions: how to start, continue, finish, constraints (size, TTL), and retry safety. For a complex multipart tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. The description adds nuance: upload_id omitted for chunk 0, chunk_index 0-based, and final=true role. However, the description does not add significant meaning beyond the schema for most parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: multipart file upload for large content exceeding token caps. It distinguishes from siblings like write_file and patch_file by specifying the multipart flow and chunk commitment mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit step-by-step flow: first call without upload_id, subsequent calls with it, and final=true to commit. It also mentions retry safety and TTL, guiding when to use this tool instead of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
view_logsARead-onlyInspect
View function execution logs with rich filtering. Each entry includes status_code, duration_ms, log_output (captured console.log), error (if any), and a derived level field (error/warning/info).
Filter by any combination of function_name, route, method, status_code (exact or 4xx/5xx wildcards), level, time range (since/until — ISO or relative like '1h'/'30m'/'7d'), full-text query across log_output and error, or specific request_id.
Use this to debug production issues: e.g. level='error' + since='1h' finds everything that blew up in the last hour.
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | Filter by severity: 'error', 'warning', or 'info' | |
| limit | No | Max entries (default 50, max 1000) | |
| query | No | Full-text search across log_output and error | |
| route | No | Filter by exact request path (e.g. /api/users) | |
| since | No | Start time — ISO 8601 or relative ('1h', '30m', '7d') | |
| until | No | End time — ISO 8601 or relative | |
| method | No | Filter by HTTP method | |
| project_id | Yes | Project ID | |
| request_id | No | Filter to a single request | |
| status_code | No | Exact code ('500') or wildcard ('4xx', '5xx') | |
| function_name | No | Filter by function name |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing the log entry fields (status_code, duration_ms, etc.) and derived `level` field. It does not mention pagination or sorting behavior, which could be useful, but overall it provides sufficient behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: a statement of what is returned, a list of filtering capabilities, and a usage example. It is concise (3 sentences) but front-loads key information. Minor improvement could be to break into bullet points for even easier scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no output schema), the description covers the main aspects: what logs contain, how to filter, and a practical usage example. It lacks details on default sort order and potential performance implications, but is largely complete for a debugging tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning by explaining the derived `level` field and providing examples of wildcards for status_code ('4xx', '5xx') and relative time formats ('1h', '30m', '7d'). It also describes full-text search across log_output and error, enriching the 'query' parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'View' and the resource 'function execution logs', accurately reflecting the tool's purpose. It clearly distinguishes from sibling tools by focusing on log viewing, while siblings like 'run_function', 'get_deployment', and 'read_file' serve different purposes. The detailed filtering options further clarify what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool, including a concrete example: 'Use this to debug production issues: e.g. level='error' + since='1h''. It also implicitly excludes other tools by describing rich filtering, which is unique among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_fileADestructiveIdempotentInspect
Write or overwrite a project file. Paths are relative to the project root.
Valid locations: public/** static files (HTML, CSS, JS, images, etc.) api/.js backend functions (each file is one endpoint) api/_lib/ shared helpers imported by api/ files, not routed migrations/*.sql database migrations, run in filename order seed.sql optional seed data, runs once on fresh installs hatchable.toml optional config overrides package.json dependencies (no build script yet)
Files are stored but not live until you call deploy.
Optional reason: a short note about why THIS specific file edit is happening. Skip it when the reason is obvious from the deploy's overall intent (most edits). Include it when the per-file purpose meaningfully diverges — e.g. "bumped vue 3.4 → 3.5 to fix the reactivity bug" on a package.json edit during an unrelated feature deploy. The reason shows up in the console next to the file's diff in the History view.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path relative to project root. Must be under public/, api/, migrations/, or one of: seed.sql, hatchable.toml, package.json | |
| reason | No | Optional. Short note (≤ 1000 chars) about why this particular edit. Only include when divergent from the deploy intent. | |
| content | Yes | File content | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. Description adds key context: files are stored but not live until 'deploy' is called, and overwrites existing files. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is compact, front-loaded with purpose, and uses bullet points for valid locations. Could be slightly more concise by removing the 'each file is one endpoint' note in api/ line, as that's implementation detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description covers input constraints (valid paths, relative root) and post-write behavior (deploy needed). Could mention character encoding or max file size, but not necessary for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the description re-iterates valid paths but does not add new meaning beyond the schema's 'description' fields for parameters. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with a clear verb-resource pair: 'Write or overwrite a project file'. It specifies scope ('relative to project root') and lists valid locations, distinguishing it from tools like patch_file (partially modify) or upload_file (likely binary).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists valid directories and file types, informing when to use this tool. However, no explicit when-not-to-use or alternatives mentioned among 30+ sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
write_filesADestructiveIdempotentInspect
Write multiple project files in a single call. Same rules as write_file but batched — faster for scaffolding a new project or updating several files at once.
Each entry in the files array has a path and content. All files are written atomically — if any path is invalid, none are written.
Optional top-level reason applies to the whole batch (typical: one logical change touching many files). Per-entry reason overrides the batch reason for that specific file when their purposes diverge.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | Array of files to write | |
| reason | No | Optional batch-level reason (≤ 1000 chars). Applied to every file in the batch unless overridden per-entry. | |
| project_id | Yes | Project ID (e.g. proj_a8Kq7fR2xZ) |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses atomicity (if any path invalid, none written) which adds value beyond annotations. The destructiveHint is true, and the description confirms it modifies files, consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs, no fluff, front-loaded with key purpose. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, and key behavior. Could optionally mention the number of files limit, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context about atomicity and the files array structure, but does not add new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool writes multiple project files in a single call, distinguishing itself from the sibling 'write_file' tool by highlighting batching and atomicity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states it is for scaffolding or updating multiple files at once, implicitly suggesting use over 'write_file' when batching is beneficial, but does not specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!