This server is a full-stack backend provisioning and management API for Run402 projects, letting an agent create and operate Postgres databases, REST APIs, auth, storage, serverless functions, static sites, and deploys without a human console.
Provision & manage projects: create Postgres projects (provision_postgres_project), list/rename/delete them, check tier pricing and usage, and manage org-level lease/admin actions.
Run SQL & REST queries: execute arbitrary SQL (run_sql), query/mutate tables via PostgREST with anon or service keys (rest_query), and introspect schema/RLS (get_schema).
Declarative authorization: apply convergent expose manifests for tables/views/RPCs (apply_expose), validate them (validate_manifest), and read the current manifest (get_expose).
Deploy apps & sites: run the full run402 up workflow (app_up), apply unified ReleaseSpecs with migrations, functions, sites, routes, subdomains, and assets (deploy), deploy static sites from inline files or directories, diagnose/resolve URLs, list/diff releases, and resume/verify deploys.
Serverless functions: deploy Node 22 functions with bundled @run402/functions helpers, invoke them, update/delete/rebuild, manage durable runs (schedule, retry, cancel, redrive), and fetch logs.
Storage & assets: upload/download/list/delete blobs, generate presigned URLs, diagnose CDN state, wait for CDN freshness, and use immutable content-addressed URLs.
Secrets & config: set/list/delete project secrets for function env injection.
CI/CD: create/list/get/revoke GitHub Actions OIDC deploy bindings with optional route scopes.
Snapshots & branches: create/list/get/restore/delete project snapshots and create/renew/delete contained branch projects.
Portable archives: export, inspect, verify, and import portable .r402ar project archives for Core/Cloud portability.
Payments & billing: call arbitrary URLs with x402 payment (pay_url), check allowance/balance, request testnet faucet, set/check tier, and list tenant payments for priced routes.
Apps marketplace: browse/fork/publish apps and list published versions.
Subdomains: claim/delete/list custom subdomains.
Project transfers: initiate, preview, accept/claim, cancel, and list incoming/outgoing project transfers.
User roles: promote/demote users to project_admin by email.
Image generation: generate PNG images from prompts (square/landscape/portrait) via x402.
Managed jobs: submit/get/log/cancel/purge platform-managed jobs and download their artifacts.
Admin/moderation: archive/reactivate projects and toggle org lease-perpetual escape hatch (platform-admin only).
Enables management of PostgreSQL databases through the Run402 platform, including provisioning, schema updates, and access control via expose manifests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@run402-mcp Provision a new hobby tier Postgres database for my app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Run402 is open-source backend infrastructure for AI agents and coding agents — a backend-as-a-service addressed to a machine rather than to a person. An autonomous agent provisions a Postgres database, user auth, file storage, serverless functions and site hosting, ships them through one staged deploy workflow, and pays for the usage itself. Comparable in surface to Supabase, Firebase or Vercel; different in that there is no dashboard you have to sign into to get started (the console exists for people; the agent never needs it) and no human-issued API key to copy.
This is the backend Kychee's open products run on. We needed a layer an agent can drive end to end, with room for whatever each app turns out to need, and nothing off the shelf had all of it, so we built it and opened it the same way we open the apps: this repo holds the agent surfaces (MIT), run402-core holds the open self-hostable runtime slice (Apache-2.0; the managed Cloud control plane remains proprietary, see CLOUD_VS_CORE.md), and kysigned is the first product running on it.
One call to run402 gives an agent a full Postgres database, REST API, user auth, content-addressed file storage, static site hosting, serverless functions, and image generation, paid with x402 (USDC on Base) or MPP (pathUSD on Tempo, or sats over Bitcoin Lightning) — or card-funded allowance. The prototype tier is free on testnet.
Run402 is agent-first because agents are first-class participants, not because people disappear. A person or agent acts through its own Run402 principal and authenticator, and its actions remain attributable. Identity answers who acted; memberships, roles, grants, grant keys, freshness, and spend policy determine what that principal may do.
An autonomous agent may remain the legitimate owner of the org-of-one it creates. People may join through explicit co-ownership. Agents entering somebody else's organization receive bounded authority instead of borrowing a human account. Different keys. Equal standing. Explicit authority.
Use the CLI by default to provision, deploy, inspect and recover. Use the typed, opinionated SDK when writing programmatic TypeScript/JavaScript workflows; shell scripts and CI can keep using CLI. MCP serves MCP-native hosts, and direct HTTP supports deliberate lower-level integrations.
This monorepo ships these interfaces:
Surface | Use when… |
Terminal, scripts, CI, agent-controlled shells: JSON in, JSON out, exit code on failure | |
Calling run402 from TypeScript: typed kernel, isomorphic (Node 22 / Deno / Bun / V8 isolates) with a Node entry that auto-loads the local keystore + wallet + x402 / Lightning fetch | |
Claude Desktop, Cursor, Cline, Claude Code: core run402 operations as MCP tools | |
OpenClaw agents (no MCP server required) | |
Buzz people and agents: install from run402.com, preflight/link one agent's dedicated identities, deploy a contextual demo, then offer human co-ownership through a normal HTTPS/passkey handoff; Buzz remains unchanged | |
Imported inside deployed functions ( | |
Astro integration for SSR, ISR cache, hosted auth components, and image variants |
These interfaces share a single typed kernel where appropriate: @run402/sdk. MCP tools, CLI subcommands, and OpenClaw scripts are thin shims over SDK calls. @run402/functions is the in-function helper that runs inside deployed code; the npm package on the registry is the artifact Cloud bundles. @run402/astro layers the SDK and functions runtime into Astro's build and SSR flow. The HTTP API is the foundation; the SDK owns shared client workflows and orchestration; CLI and MCP expose them in machine-friendly forms. Native SDK/MCP references explain intentional alternatives.
Deploy summaries share the SDK workflow view. CLI writes redacted detail under .run402/diagnostics/; MCP retains it through expand_result. Typed SDK callers keep the full result. Snapshot collection excludes platform runtime files automatically.
First create the complete run402.json and index.html from Your first deploy. Run these commands in that application directory; --name requests a new project.
npm install -g run402@latest
run402 up --name my-app -y # bootstrap wallet/tier/project/link, then deploy manifest
run402 up verify # rerun app HTTP verification without deploying
run402 up --verify # deploy, then wait for gateway/edge coherenceThat's a real Postgres database + a deployed static site, paid for autonomously with testnet USDC.
Buy from any x402 seller with the same wallet and a default $0.10 ceiling:
run402 pay https://seller.example/translate --method POST \
--body '{"text":"hello"}' --max-usd 0.05 \
--idempotency-key translation:1 --require-receiptThe SDK equivalent is
r.pay.fetch(url, init, { maxUsdMicros, idempotencyKey, requireReceipt });
MCP callers run the same SDK call as a run snippet. All three return the
same x402-commerce-result.v1 settlement, movement/replay, delivery, offer,
merchant-receipt, signer-relationship, policy, and raw-evidence fields and pass
unpriced URLs through with payment: null. Requiring a receipt rejects before
payment when no wallet-rooted offer is eligible. If a promised receipt cannot
be verified after settlement, PaymentPolicyError retains the upstream
response and paid result and tells the caller to reconcile—never to pay again.
For a
trusted Run402 PAYMENT_INTENT_PENDING, all three surfaces prescribe one
recovery path: wait for Retry-After, then repeat the same request with the
same payer and key. Never replace the key. The SDK and MCP can also re-present
an ambiguous proof while their process remains alive; custom/arbitrary sellers
remain ambiguous and require reconciliation.
Prefer run402 up when a repo has run402.deploy.json or app.json. The CLI stays a thin shim over the Node SDK action runner (r.actions.run(...) / r.up(...)): it validates the manifest first, then recursively performs only the missing prerequisites. Project resolution is --project, .run402/project.json, manifest project_id, approved creation from --name; global active state never selects a deploy target. --name is project creation/link metadata only; it is not part of the deploy manifest and never renames an existing project. Use --check for local validation and --plan for gateway-reviewed intent before applying. Local validation covers every file the manifest references (migration sql_path/sql_file, function sources and files, site paths and dir() targets, assets.put sources): a missing one fails with MANIFEST_FILE_MISSING (details.missing[] of { field_path, path, kind }, one create_file next action per file) before any gateway call, in every mode and in run402 deploy. With no manifest in the working directory, UP_MANIFEST_REQUIRED looks one directory down and names what it found (details.nearby_manifests[], a read-only run_in_directory action for a single candidate, or one unranked select_application action for multiple apps); --manifest <path> to a missing file is a typed MANIFEST_NOT_FOUND.
If an app manifest defines verify.http[], run402 up verifies those URLs after deploy. Fresh run402 edge sentinel misses are reported as propagation_pending rather than permanent failures while the binding is still converging; tune that wait with --propagation-budget-s (default 120) or return immediately with --no-propagation-wait. run402 up verify reruns the same HTTP checks without uploading, deploying, creating projects, or mutating resources.
The CLI checks for newer run402 releases opportunistically and fail-open. Success stdout stays the command result; stale-version notices are advisory JSON on stderr, or cli.update_available NDJSON events in --json-stream. run402 doctor --refresh is the explicit live npm check and reports the install context plus the safest upgrade command for local, global, or ephemeral installs. run402 doctor answers { ok, blocking[], warnings[], checks[] }: ok is true exactly when blocking[] is empty, every check carries severity: "blocking" | "advisory" | "info", advisory findings (an unbound passkey, a stale CLI, vault gaps, a tier-less own org that can still reach another org's projects: TIER_MISSING_ON_OWN_ORG) land in warnings[] without changing ok or the exit code, and the tier check's status is a fixed vocabulary (ok | inactive | frozen | past_due | dormant | purged | missing | unknown | error, never a tier name; the name and raw lifecycle are in value.tier / value.lifecycle).
Typed deploy configs use the same commands. Executable configs are trusted local code, so v1 only runs them when passed explicitly:
run402 up --manifest run402.deploy.ts --check
run402 up --manifest run402.deploy.ts --plan
run402 up --manifest run402.deploy.ts --require-plan plan_...--check and --print-spec are local-only (both verify that every referenced file exists). --plan asks the gateway for a reviewed plan with plan_id, plan_fingerprint, warnings, diff, and one next action. --require-plan reapplies only if the normalized spec and reviewed gateway events still match.
import { defineConfig, dir, nodeFunction, sqlFile } from "@run402/sdk/config";
export default defineConfig(({ env }) => ({
project_id: env.required("RUN402_PROJECT_ID"),
database: { migrations: [sqlFile("db/001_init.sql")] },
site: { replace: dir("dist"), public_paths: { mode: "implicit" } },
functions: { replace: { api: nodeFunction("dist/functions/api.js") } },
secrets: { require: ["OPENAI_API_KEY"] },
}));Helpers normalize to the same ReleaseSpec as JSON manifests. dir() walks deterministically and rejects unsafe files unless explicitly allowed, sqlFile() derives the migration id from the filename unless supplied, and nodeFunction() currently expects JavaScript output; point TypeScript functions at built .js files.
Related MCP server: Database MCP Server
Upload files with the CLI. Keep the returned AssetRef, including immutable identity and image variants, when saving references in application data. Do not reconstruct content hashes or variant URLs yourself.
run402 assets put ./logo.png ./app.js ./app.css --project prj_exampleUse a manifest asset slice when these files must activate with a release. See the storage guide and native SDK AssetRef helpers for HTML emitters and programmatic composition. Binary files must remain bytes; never read them as UTF-8 before uploading.
Tables you create are unreachable via /rest/v1/* until you declare them in a manifest. That closes the "agent created a table, forgot to set RLS, data leaked" footgun. A valid anon key against an existing but undeclared table gets a structured 403 TABLE_NOT_EXPOSED (never a bare Postgres 42501) whose next_actions say exactly that: expose_table (declare it and redeploy), edit_request (the expose endpoint), or use_function (keep it dark and read it from a function with adminDb()); it is not an RLS problem. The manifest is convergent: applying it twice is a no-op; items removed between applies have their policies, grants, triggers, and views dropped.
cat > manifest.json <<'EOF'
{
"$schema": "https://run402.com/schemas/manifest.v1.json",
"version": "1",
"tables": [
{ "name": "items", "expose": true, "policy": "user_owns_rows",
"owner_column": "user_id", "force_owner_on_insert": true },
{ "name": "audit", "expose": false }
],
"views": [
{ "name": "leaderboard", "base": "items", "select": ["user_id", "score"], "expose": true }
],
"rpcs": [
{ "name": "compute_streak", "signature": "(user_id uuid)", "grant_to": ["authenticated"] }
]
}
EOF
run402 projects validate-expose <project_id> --file manifest.json
run402 projects apply-expose <project_id> --file manifest.json
run402 projects get-expose <project_id>Built-in policies: user_owns_rows (rows where owner_column = auth.uid(); with force_owner_on_insert: true a BEFORE INSERT trigger sets it), public_read_authenticated_write (anyone reads, any authenticated user writes), public_read_write_UNRESTRICTED (fully open; requires i_understand_this_is_unrestricted: true), and custom (escape hatch: your own CREATE POLICY SQL).
Use run402 projects validate-expose for a non-mutating feedback loop before applying. Optional migration SQL is used only to check manifest references; it is not executed as a PostgreSQL dry run, and this does not validate deploy manifests.
Auth-as-SDLC: put the same JSON under database.expose in your v2 ReleaseSpec. The gateway validates it against your migration SQL during deploy and rejects mismatches with a structured errors array listing every violation.
For a standalone static directory on an existing project:
run402 sites deploy-dir ./dist --project prj_example > result.json 2> events.logUse run402 up for a complete application with a deploy manifest. The SDK owns file hashing, upload deduplication and release orchestration; the CLI renders progress and the result.
Apply-v1 routes and static public paths are release resources: the release pointer activates after the required deploy stages in run402 deploy. Applied migrations and external side effects are not rolled back by changing that pointer. Release static asset paths such as events.html are distinct from browser-visible public static paths such as /events. Use site.public_paths for ordinary clean static URLs; keep routes for function ingress and exact, method-aware static aliases.
{
"project_id": "prj_...",
"site": {
"replace": {
"index.html": { "data": "<!doctype html><main id='app'></main><script>fetch('/api/hello')</script>" },
"events.html": { "data": "<!doctype html><h1>Events</h1>" }
},
"public_paths": {
"mode": "explicit",
"replace": {
"/events": { "asset": "events.html", "cache_class": "html" }
}
}
},
"functions": {
"replace": {
"api": {
"runtime": "node22",
"source": {
"data": "export default async function handler(req) { const url = new URL(req.url); return Response.json({ ok: true, path: url.pathname }); }"
}
},
"login": {
"runtime": "node22",
"source": { "data": "export default async function handler(req) { return Response.json({ ok: true }); }" }
}
}
},
"routes": {
"replace": [
{ "pattern": "/api/*", "methods": ["GET", "POST", "OPTIONS"], "target": { "type": "function", "name": "api" } },
{ "pattern": "/login", "methods": ["POST"], "target": { "type": "function", "name": "login" } }
]
}
}site.public_paths.mode: "explicit" means only the complete public_paths.replace table is directly reachable as static URLs. In the example, /events serves the release asset events.html, while /events.html is not public unless separately declared. mode: "implicit" restores filename-derived public reachability and can widen access, so review gateway warnings before confirming it.
Omit routes or pass routes: null to carry forward base routes. Use routes: { "replace": [] } to clear the route table. Route entries are an ordered replace list, not a path-keyed map. Function targets use { "type": "function", "name": "<materialized function name>" }. Static route targets use exact patterns only, methods ["GET"] or ["GET","HEAD"], and { "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } } where file is a release static asset path, not a public path, URL, CAS hash, rewrite, or redirect. Use static route targets for method-aware aliases such as static GET /login plus function POST /login; in explicit public path mode the backing asset can stay private by filename. Direct /functions/v1/:name calls remain API-key protected; browser-routed paths are public same-origin ingress.
Function routes can charge a fixed tenant x402 price before the handler runs by adding pricing: { "mode": "always", "amount_usd_micros": 250000, "pay_to": "org_default_payout" } to the route entry. 250000 is $0.25 per matching action. The portable ReleaseSpec contract also accepts receipt: "on_fulfillment" on a priced function route; a compatible host then requires the function to return payment.fulfilled(response) before it authors a receipt. Run402-hosted advertising remains gated off until the standard delegated-signer carrier is available—receipt intent never silently downgrades. Omit networks for production mainnet only; include "testnet" explicitly for testnet acceptance. Static aliases cannot be priced, direct function invocation is not monetized, and service/admin keys do not bypass a priced browser route. The owning org must have a resolvable payout wallet: set it with run402 orgs payout-wallet <org_id> <wallet_address>. Conditional credit systems should expose one fixed-price route such as POST /api/credits, then keep the rest of the app behind unpriced routes and app-local authorization.
Matching is exact or final-prefix-wildcard only. /admin and /admin/ are exact trailing-slash equivalents; /admin/* matches children but not /admin, /admin/, /admin.css, or /administrator, so deploy both /admin and /admin/* for a routed section root. Query strings are ignored for matching and preserved in the handler's full public req.url. Exact routes beat prefix routes; longest prefix wins; method-compatible dynamic routes beat static assets. A POST /login route can coexist with static GET /login HTML. Unsafe method mismatch returns 405, and matched dynamic route failures fail closed instead of falling back to static files.
Routed functions use the Node 22 Fetch Request -> Response contract: export default async function handler(req) { ... }. req.method is the browser method, and req.url is the full public URL on managed subdomains, hosts, and verified custom domains. Derive OAuth callbacks from it, for example new URL("/admin/oauth/google/callback", new URL(req.url).origin). Append multiple cookies with headers.append("Set-Cookie", value); redirects, cookies, and query strings are preserved. On priced routes, import getRoutedPaymentContext from @run402/functions, read const paymentContext = getRoutedPaymentContext(req), and key app-side idempotency by paymentContext.paymentId. For a receipt-enabled route, return payment.fulfilled(response) only after the response represents completed delivery; the helper fails closed outside a settled, current, receipt-enabled routed invocation. The context helper reads gateway-confirmed x-run402-payment-* headers and returns null for unpriced or direct calls. The raw run402.routed_http.v1 envelope is internal; do not write route handlers against it.
Recipe: static home page + SPA shell. A SPA site ships index.html as the shell serving every unmatched route (match spa_fallback), so by default GET / serves the shell too. To serve a real static home page at / while keeping the shell for app routes, ship home.html at the site root alongside index.html and add an exact root static route alias: "routes": { "replace": [ { "pattern": "/", "target": { "type": "static", "file": "home.html" } } ] }. Route matching runs before all static resolution (including the implicit / -> index.html root mapping), and SPA-fallback derivation is independent of the route table, so GET / serves home.html (route_static_alias), unmatched app routes such as /dashboard still serve the shell (spa_fallback), and named static pages keep serving unchanged (static_exact). Expect two non-blocking plan lints: STATIC_ALIAS_SHADOWS_STATIC_PATH (warn: the alias overrides what / would otherwise serve; accurate and expected here) and STATIC_ALIAS_DUPLICATE_CANONICAL_URL (info: /home.html stays directly reachable in implicit public-path mode; add <link rel="canonical"> to home.html if duplicate-content SEO matters). Omitting routes on later deploys carries the alias forward; routes.replace is total, so a pipeline that sends it must include the alias every time. Verify with run402 deploy resolve --url https://<your-site>/ --method GET (or r.project(id).apply.resolve) and confirm match: "route_static_alias" with target_file: "home.html".
Avoid routing every static file, broad method lists by default, wildcard static route targets, leading-slash static files, directory shorthand, and one-static-route-target-per-page tables that exhaust route limits. Also watch wildcard function routes that shadow direct public static paths. Warning codes to handle include STATIC_ALIAS_SHADOWS_STATIC_PATH, STATIC_ALIAS_RELATIVE_ASSET_RISK, STATIC_ALIAS_DUPLICATE_CANONICAL_URL, STATIC_ALIAS_EXTENSIONLESS_NON_HTML, and STATIC_ALIAS_TABLE_NEAR_LIMIT; inspect active routes, static_public_paths, and resolve diagnostics to distinguish the route pattern from the backing asset_path.
Resolve public URLs with the CLI or its MCP/SDK equivalents:
run402 deploy resolve https://example.com/events --project prj_123 --method GET
run402 deploy resolve --url https://example.com/events?utm=x#hero --project prj_123 --method GET
run402 deploy resolve --host example.com --path /events --project prj_123 --method GETr.project(id).apply.resolve({ url, method: "GET" }) (from MCP, a run snippet) returns would_serve, diagnostic_status, match, normalized request data, warnings, full resolution JSON, edge_propagation, and next steps. When returned, asset_path, reachability_authority, and direct explain which release asset backs the public URL and whether reachability came from implicit file-path mode, explicit site.public_paths, or a route-only static alias. Stable-host diagnostics may also include authorization_result, cas_object (sha256, exists, expected_size, actual_size), hostname-specific response_variant, route/static fields such as allow, route_pattern, target_type, target_name, and target_file, and edge_propagation (settled, propagating, or sync_pending). Known match literals are host_missing, manifest_missing, active_release_missing, unsupported_manifest_version, path_error, none, static_exact, static_index, spa_fallback, spa_fallback_missing, route_function, route_static_alias, and route_method_miss; preserve unknown future strings. Known authorization_result values include authorized, not_public, not_applicable, manifest_missing, target_missing, active_release_missing, unsupported_manifest_version, path_error, missing_cas_object, unfinalized_or_deleting_cas_object, size_mismatch, and unauthorized_cas_object. Known fallback_state values include active_release_missing, unsupported_manifest_version, and negative_cache_hit; preserve unknown future strings. result is the diagnostic body status, not the HTTP status of the SDK call, so host misses can still be successful CLI/MCP/SDK calls with would_serve: false. Do not treat resolve/diagnose as a fetch, cache purge, or cache-policy oracle; route method misses should inspect allow, CAS authorization/health failures should inspect or redeploy the affected static asset, and fresh host misses should inspect edge_propagation or rerun run402 up verify. Branch on structured JSON fields such as cache_class and preserve unknown cache classes.
Release observability exposes stable asset identity and public reachability. Inventories include release_generation, static_manifest_sha256, nullable static_manifest_metadata (file_count, total_bytes, cache_classes, cache_class_sources, spa_fallback), and static_public_paths[] when returned. site.paths lists release static assets; static_public_paths[] lists browser-visible public paths with public_path, asset_path, reachability_authority, direct, cache class, and content type. Plan and release diffs expose static_assets counters: unchanged/changed/added/removed, newly_uploaded_cas_bytes, reused_cas_bytes, deployment_copy_bytes_eliminated, legacy_immutable_warnings, previous_immutable_failures, and cas_authorization_failures.
Runtime route failure codes to branch on: ROUTE_MANIFEST_LOAD_FAILED (manifest/propagation), ROUTED_INVOKE_WORKER_SECRET_MISSING (custom-domain Worker secret), ROUTED_INVOKE_AUTH_FAILED (internal invoke signature), ROUTED_ROUTE_STALE (selected route failed release revalidation), ROUTE_METHOD_NOT_ALLOWED (method mismatch), PAYOUT_WALLET_REQUIRED / PAYOUT_WALLET_AMBIGUOUS / PAYOUT_WALLET_UNRESOLVED (priced-route payout setup), PAYMENT_PROOF_MISMATCH (stale or wrong x402 proof), and ROUTED_RESPONSE_TOO_LARGE (body over 6 MiB).
For repo-driven deploys, run402 does not need service keys or wallet files in GitHub secrets. Run a local link command once:
run402 ci link github --project prj_... --manifest run402.deploy.json
# Optional route authority for CI route declarations:
run402 ci link github --project prj_... --manifest run402.deploy.json --route-scope /admin --route-scope /api/*That creates a deploy-scoped /ci/v1/* binding and writes a workflow that grants id-token: write, checks out the repo, and runs the existing deploy primitive:
permissions:
contents: read
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy to run402
run: npx --yes run402@3.7.5 deploy --manifest 'run402.deploy.json' --project 'prj_...'CI deploys are intentionally narrow: site, functions, database, absent/current base, and route declarations only when the binding has covering --route-scope patterns. Without route scopes, CI cannot ship routes. Keep secrets, domains, subdomains, checks, non-current base, and broader trust changes in a local wallet-backed deploy. If the gateway returns CI_ROUTE_SCOPE_DENIED, re-link with exact scopes like /admin or final-wildcard scopes like /api/*, or deploy locally. Manage bindings with run402 ci list and run402 ci revoke.
Inside a deployed function, import from @run402/functions. Two distinct DB clients keep RLS clean:
import { db, adminDb, auth, email, ai } from "@run402/functions";
export default async (req: Request) => {
const user = await auth.requireUser();
// Caller-context: db() mints a 60s actor JWT so run402.current_user_id() resolves in RLS.
// No .eq("user_id", user.id) needed: RLS already binds the visitor's rows; the redundant
// filter is a deploy-fail (R402_AUTH_REDUNDANT_USER_FILTER) under @run402/functions v3.0+.
const mine = await db().from("items").select("*");
// BYPASSRLS: for platform-authored writes (audit logs, cron cleanup, webhook handlers).
await adminDb().from("audit").insert({ event: "items_read", user_id: user.id });
// Send mail from the configured default outbound mailbox.
if (mine.length === 0) {
await email.send({ to: user.email, subject: "Welcome", html: "<h1>hi</h1>" });
}
return Response.json(mine);
};adminDb().sql(query, params?) runs raw parameterized SQL and always bypasses RLS. The current runtime returns the gateway envelope, including rows and row_count; read result.rows, not result[0]. Older helper typings incorrectly described a bare array. See the owning runtime reference and match local helper types to the runtime version used by your deploy.
@run402/functions is auto-bundled into deployed code; install it in your editor for full TypeScript autocomplete (also works at build time for static-site generation with RUN402_SERVICE_KEY + RUN402_PROJECT_ID set).
ai.generateImage({ prompt, aspect? }) is available inside deployed functions for live app flows such as generated avatars or OG images. It calls the project runtime image endpoint with RUN402_SERVICE_KEY, so deployed functions do not need wallets or x402 signing code. Aspects are square, landscape, and portrait; the result is { image, content_type, aspect } with base64 image bytes. Runtime image generation is billed, rate-limited, and spend-capped against the project organization; public routed functions should authenticate/rate-limit their users before calling it.
assets.put(key, source, opts?) uploads bytes from inside a deployed function through the same CAS-backed apply substrate as deploy-time assets. It uses RUN402_SERVICE_KEY, accepts a string, Uint8Array, or { content | bytes }, and returns an SDK-compatible AssetRef with mutable and immutable URLs.
Operating data from outside a function: use the CLI with an explicit project. For deliberate HTTP integrations, the native HTTP reference distinguishes administrative REST from caller-scoped REST. Never expose a service key to the browser.
run402 projects sql prj_example "SELECT count(*) FROM audit"run402 repos is a Git remote whose contents are encrypted on your own machine and stored as a chain of signed, admitted heads. It exists so your repository history outlives the machine it was written on — without that outliving requiring you to hand Run402 the plaintext. The wire protocol is r402s/v0. One noun, seventeen verbs: KyGit is the brand, a vault is the resource, a repo is what you have — run402 repos on the command line and r.repos in the SDK. Two pairs of the seventeen mint and claim a single-use bearer key: handoff/resume hand a checked-out working tree — dirty state included — from one agent to ANOTHER, the sender stopping; invite/join bring a SECOND agent into the SAME work while the first keeps going, sharing a coordination room. See "Handoff / resume" and "Invite / join" below.
Three claims, three different strengths. These are the entire approved claims vocabulary for this feature:
Run402 cannot decrypt your vault or repository history. Deployment artifacts remain a disclosed plaintext custody boundary. Cryptographic, against Run402 itself: in the vault lane, source payload and repository-history content are ciphertext-only; the substrate retains only enumerated plaintext metadata and holds zero vault keys. The deploy lane is separate and disclosed — the platform custodially holds the plaintext artifacts of every deploy. It can read what you deployed; it cannot read what you did not.
Activation requires vault admission by default; an explicit, audited override can bypass it. An operational platform invariant, enforced and auditable — not cryptographic against the platform that enforces it.
Retention is an operational promise of the platform, not a cryptographic guarantee against it (the host controls timestamps and bytes).
The vault-only track — three lines, muscle memory intact, nothing to pay:
run402 init # once per machine
run402 repos create my-notes # project + vault + origin remote, one free call
git push -u origin main # publishes, encrypted before it leaves the machineorigin is claimed additively: when the directory has no origin yet, the scaffold names ours origin — git push origin main just works, no side-remote name to remember. An existing origin is never touched; the fallback is run402 instead, and the response says which happened and why. An app that lives inside another repository (a monorepo workspace) is never scaffolded into that repository: the skip carries a create_nested_repo next action, and run402 repos create --nested --project <project_id> (or run402 up --nested) gives the app root its own nested repository and run402 remote, appending exactly one line to the enclosing repository's local .git/info/exclude and touching nothing else there; repos create prints a git push next action only for a remote it actually added. The free path is the whole path — no slug, no fee, no ceremony. When you want pretty run402::<org-slug>/<name> addresses (clone-by-name, push-to-create), claim an org slug once — the optional named-address upgrade described below.
Named addressing. run402::<org-slug>/<name> works alongside the id-form run402::<org_id>/<project_id> in the same slot — pick an org slug once (run402 orgs slug <slug>, owner-only, a small one-time fee), and every repo under it is run402::<slug>/<name>. Pushing a name that doesn't exist yet push-to-creates it: the project and vault are allocated atomically, and a losing concurrent pusher resolves cleanly to the winner's repo instead of erroring — its work is not lost, it just wasn't the creator. The first time a named remote resolves on a checkout, the resolved id is pinned into that checkout's local git config — every later push/fetch follows the pin directly, so a later rename of the org slug or repo name never breaks an existing clone. The id-form address needs no pin (a project id never changes) and stays the cold-restart path: an agent that lost its local state but still holds authority on the project can always fall back to run402::<org_id>/<project_id>.
One thing to know up front: a vault has a writer set, not a single key. Every admitted member or handoff recipient opens the vault and pushes under its OWN keystore key (run402 repos access lists them). A vault whose only admitted principal is this keystore is exactly as safe as this keystore — see "If you lose the keystore" below, or admit a second principal.
The explicit, ceremonial form still works, and allocates the SAME way git push does lazily on first use — useful for scripts, or for the receipt to land in JSON stdout instead of stderr:
# 1. Provision. Inside a repository that already exists, this adds the origin
# remote (run402::<org_id>/<project_id>). Not a repository yet?
# `run402 init --git-remote` creates one first. It needs a project selected
# (`run402 projects use <project_id>`, or RUN402_PROJECT_ID).
run402 init
# 2. Allocate the repo's vault explicitly. Separate from `run402 init` on
# purpose: this is the step that mints key material on this machine and
# prints a one-shot recovery receipt. Idempotent — an existing vault comes
# back deduplicated. (Skip this step and git push / repos capture
# against an unallocated project allocates the SAME way, lazily, on
# first use — the two paths don't stack; this one just does it now,
# explicitly, so the receipt lands in JSON stdout instead of stderr.)
run402 repos create --project <project_id>
# 3. Snapshot — capture the working tree, encrypt it, publish a signed head.
run402 repos capture --message "wip: refactor the parser"
git push origin main # ...or push your own branches, via git-remote-run402
# 4. View, then fsck: walk the head chain from your authenticated pin.
run402 repos view
run402 repos fsck --budget 500
# Restore anywhere, with plain git.
git clone run402::<org_id>/<project_id> restoredCloning needs a Run402 principal on this machine — a wallet and a keystore holding an envelope for this vault — this is encrypted git, not a shareable link.
A fresh clone installs local refs/r402/retain/<oid> refs for every retained deploy-capture tip no branch reaches, so a plain git fsck is silent — git for-each-ref refs/r402/ lists what is retained. Clones made by a client older than this one (or a checkout whose ref write degraded) may still show dangling commits under git fsck; harmless, not corruption — one run402 repos fsck run installs the missing refs. A retained ref locally pins that history against git gc until the vault prunes the capture, at which point the next fetch retracts it.
repos capture is the CAPTURE lane — the protocol deploy ref plus the HEAD target — because a dirty tree captures as a synthetic commit that sits on no branch. Your own branches and tags reach the vault through git push origin <branch>.
Allocating a vault does NOT gate the project's deploys. vault_policy stays unset until you set it — a vault created by a first git push or repos create never silently changes how you deploy. A deploy against a vaulted, ungated project proceeds ungated and its result carries a typed next_actions entry offering run402 repos policy required; every later ungated deploy carries a warnings[] entry naming the drift, until the policy is set either way — never a block, never an interactive prompt. Once vault_policy is required, a deploy must present a vaulted capture at commit — run402 deploy produces one automatically on any machine holding the keystore; un-gate with run402 repos policy grandfathered --reason "<why>" (owner + step-up, audited, reversible with run402 repos policy required). Vaulting your source is never gated on a deploy, either way. run402 doctor reports the policy, whether this machine can satisfy it, and where the keystore lives.
Before capture reports that anything landed, the client compares every finalization receipt against its local expected manifest and reads the admitted head back from storage — a 200 alone is never enough. Maintenance is one verb, run402 repos gc — git gc's own two halves (checkpoint publication + prune planning), never described as "exactly git gc" since the deletion ceremony is stricter: it plans locally, and submits only when handed both verifier receipts — one from this CLI, one from the independent r402s-verify — with --submit --intent-core <path> --verifier-receipt <path>; only the control-plane-signed completion says what was deleted.
From the SDK, with identical semantics — vault reads run anywhere, and the verbs that touch a git working tree or the on-disk keystore are Node-only:
For typed repository automation, see the native SDK KyGit reference.
The encrypted second remote — the zero-migration pattern. Keep GitHub/GitLab as the primary (collaboration, CI, reviews, unchanged) and add KyGit as the second remote: git remote add vault run402::<org_id>/<project_id> + git push vault --all, and a complete, continuously updated copy of your history exists that the storage provider itself cannot read. The reason this matters, said plainly and as capability rather than accusation: a host that can READ private repositories can — under a future policy, an acquisition, a training pipeline, a subpoena, or a breach — index them, train models on them, or hand them to someone who will. Run402 cannot decrypt your vault or repository history. Deployment artifacts remain a disclosed plaintext custody boundary.
A vault-only project is first-class. run402 init (or run402 repos create <name>), then git push origin …, then gc / fsck / access, and never a deploy — a supported shape, not a degraded one. One consequence is worth stating plainly: a vault-only project has no deploy lane, so the disclosed plaintext custody boundary is empty and there is consequently no custodial restore path.
If you lose the keystore. The vault protects source history from host-side loss while a principal keystore survives. The "while" clause is load-bearing: in V0-A, whole-machine or whole-keystore loss is terminal for vault history until human envelopes ship, and run402 repos view prints that sentence verbatim. Back up the keystore directory run402 repos view reports as keystore.root and prints under the terminal-loss statement — ~/.config/run402/vault for the default wallet, ~/.config/run402/profiles/<wallet>/vault for a named one. The recovery receipt is an integrity anchor, not a decryption key — it proves the vault you are served is the one you created, and it decrypts nothing. It is not a secret; the more copies the better. The reminder gets louder as the vault gets more valuable: quiet at genesis, a STANDING run402 doctor warning once the vault crosses any of ≥10 generations / ≥10 MB / ≥14 days since genesis — cleared only by adding a second principal, never by an attestation, because V0 cannot verify one is true.
The exit ramp: mirror your own copy. run402 repos mirror <destination> [--profile <name> | --ambient] (S3 or a plain directory) configures a second, customer-owned copy of the vault's ciphertext — the destination and credential name live in a config file beside the keystore, never in run402.config.json, never a raw secret. Once set, every capture is mirrored to it automatically, reported as a separate mirror_push field beside the vault result; a mirror failure never blocks, slows, or changes the actual publish. run402 repos mirror --backfill (idempotent, resumable) catches it up on demand; run402 repos fsck --mirror is a KEYLESS integrity probe — it reports the recoverable generation without touching key material. run402 repos recover <source> --out <dir> needs no server at all: it reads the mirror, verifies the chain, and decrypts with the local keystore alone. Named recover rather than restore, which already means something else in git. Two things to know before you rely on it: it proves validity, never freshness — an older mirror looks identical to a genuinely short history — and a mirror without the keystore or an equivalent key recovers nothing, since mirroring ciphertext does not create a second key; the V0 terminal-loss statement above applies.
The human backup path (vault-recovery-custody). A human org member who completed source enrollment at console.run402.com/account holds an equivalent key with no keystore at all: their member key lives as sealed wrappers (passkey PRF and/or a source recovery code), and run402 repos recovery-bundle downloads the versioned recovery bundle (key identity + wrapper ciphertexts — still nothing the platform can open). Kept with a vault mirror — copy it to member-recovery-bundles/<name>.json under the mirrored prefix — that bundle + the source recovery code + the vault's recovery receipt recover the repository with no run402 server and no keystore: run402 repos recover <source> --out <dir> --receipt <pin.json> (the code is prompted with hidden input; --bundle <file> if the bundle isn't in the mirror). A raw passkey PRF output is deliberately NOT a recovery input — the no-server path for a human is the recovery code. run402 doctor's recovery_posture check tells you whether each vault-owning org actually has this backstop configured.
run402 repos mirror s3://acme-vault-mirror --profile acme --region us-east-1
run402 repos mirror --backfill
run402 repos recover s3://acme-vault-mirror --out ./restored --repo src_1a2b3c
run402 repos recovery-bundle --out ./bundle.json # the member's no-keystore recovery half
run402 repos recover ./mirror-copy --out ./restored --receipt ./recovery-receipt.json --bundle ./bundle.jsonHandoff / resume — pass a working tree to another agent, dirty state and all. run402 repos handoff captures the actual working tree — staged, unstaged, and untracked changes, exactly as git stash push -u would — and mints a single-use bearer key, kgh1_…, printed to stdout exactly once (--json still keeps it off stderr; there is no second place to find it if you lose it). Hand that key to another agent — another machine, another session, no shared keystore, no shared wallet — and run402 repos resume kgh1_… claims it, clones a fresh checkout, and reapplies the exact dirty state with git stash apply --index. The resuming agent also becomes a run402 wallet of its own on the way in: with no active tier, resume folds the same cold-start chain create does (wallet → faucet → one x402 prototype payment) before the claim; --no-init opts out, and the claim never waits on it. A Handoff Note rides alongside (a short JSON summary: what's done, what's in progress, what's failing, next steps) and renders as Markdown by default on resume. The key confers real authority — by default the sender's own org role — until it is claimed or its TTL (default 1h, --ttl <seconds>) expires; the mint response says so, and the CLI echoes the warning before printing the key. Sensitive untracked files (.env, *.pem, *.key, SSH/AWS/GPG directories, and 18 more patterns) are excluded from capture by default; opt one back in with --include-sensitive <glob>.
run402 repos handoff --note-file handoff.json # captures the working tree, mints the key, prints it ALONE to stdout
run402 repos resume kgh1_… # on the other machine: redeem it, clone, restore, print the noteNeither verb has an MCP tool — handoff mints a bearer secret and resume mutates org membership, the same "mutating verbs are CLI-only" reasoning as create/delete above.
Writers, plural. A vault admits heads from a SET of writer keys, each a member's own keystore identity (protocol rev 47). resume makes the recipient a writer before it returns — git push works at once, under the recipient's own key, and the sender's environment can be deleted afterwards. Any member added with run402 orgs members add (developer or above) becomes a writer the same way: the adder's client admits the new key inline when it can, and REFUSES the add (VAULT_WRITER_NOT_ADMITTED, request_writer_sync) when it cannot, so no member is ever left able to read but not push. run402 repos view lists writers[] and pending_writers[]; run402 repos access sync admits pending keys on demand; removing a member rides the next epoch rotation and that key can never be re-added. Nobody's seed is ever copied: a writer is admitted by a live writer's signature or by a sender-signed handoff grant the recipient completes with its own key.
Invite / join — bring a second agent into the exact work, dirty tree included, and talk in a shared room. A Handoff passes the work on; an Invite grows the team. run402 repos invite captures the working tree exactly like handoff does — the inviter's own worktree, index, branch, refs, and access are all untouched, and it keeps pushing throughout — registers the inviter's own presence in a coordination room (the project's default room, or --room <key> for a named org room), mints a single-use bearer key, kgi1_…, printed to stdout exactly once, and posts ONE room message naming the checkpoint and the invite id (never the key). Minting requires an ACTIVE writer key, the same as handoff (INVITE_MINT_REQUIRES_WRITER names run402 repos access sync as the fix). Hand that key to another agent and run402 repos join kgi1_… pays its own way in — the joining agent folds the SAME cold-start chain resume does (wallet → faucet → one x402 prototype payment) before the redemption, so it arrives as a paid-up run402 wallet of its own — clones a fresh checkout, becomes a writer of the vault under its OWN key before the command returns (nothing is copied from the inviter), restores the exact dirty state, pins the invite's room locally, registers its own presence, posts ONE arrival message, and reports who invited it (name, labels, whether they're still live), who else is in the room, and the last few messages. Both agents push, interleaved, each signing under its own key. From there run402 messages wait is the agent's ear: it blocks until the other side speaks (or a bounded timeout elapses) using the gateway's held read, never errors on silence, and reports who is still live either way. The minted role defaults to developer and never exceeds the inviter's own; the Invite Note (same shape as the Handoff Note) rides alongside and renders as Markdown by default on join. Taking access back is run402 orgs members rm, which rotates the vault's epoch so the removed key can no longer push while every remaining agent keeps working.
run402 repos invite --note-file invite.json # captures the working tree, mints the key, prints it ALONE to stdout
run402 repos join kgi1_… # on the other machine: pay in, redeem, become a writer, clone, restore
run402 messages wait # then: block until the other agent speaks (or the timeout elapses)Like handoff/resume, neither invite nor join has an MCP tool — invite mints a bearer secret and join mutates org membership and writes a working tree, the same reasoning as create/delete/handoff/resume above.
Verify it without trusting our client. r402s-verify is an independent-lineage verifier for the same protocol — a separate language, separate authorship, and a separate primitive stack, deliberately sharing no implementation code with the SDK. That non-sharing is the point: a differential verifier that reuses the code it is checking verifies nothing. It lives on the r402s-verify branch of this repository with its own workflow, ships prebuilt release binaries, and also builds with cargo build --release. The full protocol specification and threat model it verifies against are published in docs/kygit/, and the frozen conformance vectors in test-vectors/r402s-v0/.
Cost. There is no separate repos price — a vault's bytes count against the organization-pooled vault quota (sourceBytes: prototype 1 GB, hobby 10 GB, team 50 GB), a separate pool from the storage your projects share, charged once per unique object with a 4 KiB per-object accounting floor and a 1 MiB per-vault minimum.
@run402/sdknpm install @run402/sdkTwo entry points:
@run402/sdk: isomorphic. Bring your own CredentialsProvider (a session-token shim, a remote vault, anything that resolves project keys + auth headers). Works in Node 22, Deno, Bun, V8 isolates.
@run402/sdk/node: Node-only convenience. Reads local profile state plus the project-key credential cache (credentials/project-keys.v1.json) and signs x402 payments from one deterministic source: an explicit opaque paymentSigner, explicit walletPath, the supplied provider's readWallet(), or the default active-profile wallet. Auth and payer may intentionally differ; a selected payment source never falls back to an ambient wallet. r.paymentPayer() reports only safe public payer/source provenance. Also exposes sites.deployDir(...), fileSetFromDir(...), typed deploy-manifest helpers (loadDeployManifest, normalizeDeployManifest), and resolveRun402TargetProfile() for app build scripts that need the same Core/Cloud target the CLI uses.
import { run402 } from "@run402/sdk/node";
const r = run402();
// Prepare the complete first-deploy manifest and referenced app files.
const result = await r.up({ name: "my-app", manifest: "run402.json" }, { approval: "yes" });
console.log(result);The SDK is organised into focused namespaces: actions (Node recursive action runner), pay (bounded arbitrary-URL x402 buyer), projects, snapshots, branches, archives, assets, cache, ci, sites, functions, jobs, secrets, subdomains, domains, email (+ webhooks), auth, apps, tier, billing, contracts, ai, wallets (the local wallet: status, create, export, faucet; plus the server label), service, admin, session (a person's sign-in session: run402 login loopback and --device seams plus the browser surface), writeApproval (the passkey write approval behind run402 approve), me (account overview and status), wallets (signed server-side wallet label), orgs (org-owned control plane + r.org(id) sub-client), grants (per-project capability grants), and identityLinks (public, protocol-discriminated human/agent Nostr attribution), plus const project = await r.project(id); await project.apply(spec) for staged multi-resource writes (release slices + assets slice via /apply/v1/*). Every operation throws a typed Run402Error subclass on failure: PaymentRequired, PaymentBuyerError, ProjectNotFound, Unauthorized, ApiError, NetworkError, LocalError, Run402DeployError. apply() automatically re-plans safe current-base BASE_RELEASE_CONFLICT races and emits apply.retry progress events. See sdk/README.md.
Humans and agents can publicly attribute separately held Buzz/Nostr identities to their Run402 principal. Agent links use the EOA-plus-kind-1 protocol; human links use a normal browser, fresh passkey, and released Buzz consent ceremony at https://console.run402.com/identity-links/connect. Both produce the same public idlnk_… resource shape with a discriminating proof_protocol. One principal may have several active Nostr subjects, while one active Nostr subject belongs to only one principal. This is attribution only: Nostr identities never authenticate, authorize, pay, deploy, or receive transfers. Run402 never accepts or derives from an nsec, Nostr private key, mnemonic, seed, passkey, session credential, or derivation path.
The human-facing install is a Buzz message—no terminal required:
Please install the run402.com skill.That is the entire human instruction. In a managed Buzz context, first-party discovery routes it to run402-buzz; the agent reads the apex install router and installs the self-contained skill into its workspace (normally the user-home .buzz directory). The request means install and connect: after verifying the inert files, the agent loads the installed skill directly and continues through preflight, setup, and identity linking in the same turn. It does not stop at “available next turn” or ask a second setup question. For a Codex runtime, prefer supplying the working directory and environment separately to the agent's command runner:
working_directory: <user-home>/.buzz
environment: { "DO_NOT_TRACK": "1" }
command: npx --yes skills@latest add https://run402.com -s run402-buzz -a codex -yShell-only POSIX environments use:
cd "$HOME/.buzz"
DO_NOT_TRACK=1 npx --yes skills@latest add https://run402.com -s run402-buzz -a codex -yWindows PowerShell uses:
Set-Location (Join-Path $HOME '.buzz')
$env:DO_NOT_TRACK = '1'
npx --yes skills@latest add https://run402.com -s run402-buzz -a codex -yClaude Code uses -a claude-code, Goose uses -a goose, a confirmed .agents/skills consumer may use -a universal, and Claude Code plus Codex uses -a claude-code codex. universal is the shared path, not all runtimes; do not use the invalid explicit target -a claude. The skill bytes come from immutable digest-verified artifacts at run402.com; first-run npx can still require npm. GitHub is the one availability-only fallback, while any integrity failure stops before setup. Success reports the observed first-party digest and exact managed-workspace path; a GitHub source or global runtime path is never mislabeled first-party.
The file installation stage is inert. Continuing onboarding publishes a durable public kind-1 Nostr event and durable Run402 proof connecting the two public identities; revocation does not erase their history, and a Buzz-managed event may also expose its owner's public NIP-OA attestation. The agent initializes only if needed, creates or reuses the link, independently verifies it, and immediately offers one context-relevant quick test or demo with Deployment: none retained in the expanded receipt. On Windows the setup helper runs npm's and Run402's JavaScript entrypoints through the exact managed Node runtime with shell: false, avoiding .cmd process-boundary failures. It waits for explicit approval before building or deploying. After independently verifying the live app, it creates an inert durable offer and posts a normal HTTPS “Become an owner” handoff. The browser owns human login/passkey and the existing Buzz six-digit consent callback; no human terminal command or Buzz change is required.
See the buzz/ guide for prerequisites, the no-secret signer model, released-client fixtures, migration guidance, and the full workflow, or inspect the exact run402-buzz listing on skills.sh. The low-level CLI commands remain available for debugging, but they are not a competing onboarding path.
The community control plane keeps four concepts separate: installing the skill is inert shared capability; installing a community associates a Buzz relay community with a Run402 organization after dual consent; human adoption records a terminal consent receipt, creates the human's public Buzz identity link, and adds an ordinary owner membership without demoting the founder agent; agent enrollment gives each later agent principal only bounded, expiring grants to named existing projects. The completed receipt, public attribution, and membership remain independent: revoking the link does not remove org authority, and removing the membership does not revoke the link or rewrite the receipt. Buzz itself remains unchanged: approval uses already-shipped browser-fragment/kind-1 behavior plus released NIP-11/NIP-43 evidence, while Run402 owns offers, organizations, descriptor discovery, and lifecycle. run402 buzz status capability-detects older gateways; MCP only renders exact HTTPS/CLI next steps. See the Fizz/Honey workflow.
Astro SSR + ISR cache. For Astro apps, use @run402/astro 1.0+: export default run402(); in astro.config.mjs returns an AstroUserConfig composing the SSR adapter (Lambda + SnapStart + ISR cache + AsyncLocalStorage request-context), image integration, and build-time detectors. Functions opt into the SSR class via FunctionSpec.class: "ssr" in ReleaseSpec; the gateway provisions SnapStart and caches HTML responses keyed by (host, path, search, method, locale, release_id). Cache is bypass-by-default (no-store unless Cache-Control explicitly allows it AND no Set-Cookie AND no auth-taint flag from auth.* helpers / payment primitives). Invalidate from in-function code or out-of-band: r.cache.invalidate(url) / r.cache.invalidatePrefix({ host, prefix }) / r.cache.invalidateAll({ host }) (SDK), run402 cache invalidate <url> (CLI). Inspect cached state with r.cache.inspect(url) / run402 cache inspect <url>. Agent DX helpers also in the CLI: run402 doctor (5 health checks), run402 dev (Astro dev with .env.local), run402 logs --request-id req_... (correlate across functions). Full reference at astro/README.md and cli/llms-cli.txt (R402_* SSR Runtime Error Codes section).
run402npm install -g run402@latestEvery subcommand prints JSON to stdout, JSON errors to stderr, exits 0 on success and 1 on failure: designed for an agent shell, not a human. Full reference: cli/llms-cli.txt (also at https://docs.run402.com/llms-cli.txt) — an index carrying the whole first-deploy contract plus a table of fetchable topic slices (/llms-cli-deploy.txt, /llms-cli-commands.txt, /llms-cli-functions.txt, …); /llms-cli-full.txt is the whole thing in one document.
run402 up --name my-app -y # recursive SDK action runner: init/tier/project/link/deploy
run402 up verify # rerun app HTTP verification without a deploy
run402 up --nested -y # app root inside another repo: its own nested repo + encrypted remote
run402 doctor # { ok, blocking[], warnings[], checks[] }: ok means this agent can ship
run402 logs --request-id req_abc123 # every function in the project; app output only (--all for the raw stream)
run402 init # one-shot wallet + faucet + tier check
run402 pay https://seller.example/resource --max-usd 0.05 --require-receipt
run402 status # organization snapshot (wallet, rail, balances, tier, projects)
run402 projects provision --name my-app
run402 projects sql <project_id> "CREATE TABLE …"
run402 projects validate-expose <project_id> --file manifest.json
run402 projects apply-expose <project_id> --file manifest.json
run402 sites deploy-dir ./dist
run402 deploy verify op_... --project <project_id> --wait # confirm gateway/edge release coherence
run402 deploy releases active --project <project_id> # inspect current-live release inventory
run402 deploy resolve https://example.com/events --project <project_id> --method GET
run402 deploy --manifest app.json --json # deploy only; rehearses automatically when a live release has migrations to protect
run402 snapshots list prj_...
run402 branches create prj_... --ttl-days 7 --json
run402 functions deploy <project_id> <name> --file fn.ts
run402 functions runs create <project_id> <name> --event-type reminder.send --idempotency-key reminder:123 --delay 10m
run402 ci link github --project <project_id> # GitHub Actions OIDC deploy binding (--route-scope for CI routes)
run402 assets put ./asset.png --immutable
run402 assets diagnose <url> # inspect live CDN state for a public URL
run402 cdn wait-fresh <url> --sha <hex> # poll until a mutable URL serves the new SHAup is the only compound CLI command: it calls the SDK action runner, emits steps[], and writes .run402/project.json when it needs to remember the workspace project. Against run402 Core it skips Cloud wallet/tier prerequisites and fails closed if no Core project is selected.
Rehearsal is automatic: a migration-bearing run402 up / run402 deploy against a project with a live release is rehearsed on a contained branch and committed only on a passing report (result.deploy.rehearsal); a first deploy has nothing to protect and commits directly (reason: "no_live_release"), and a redeploy whose migrations are all already applied with identical checksums is skipped as migrations_unchanged, so a page-only redeploy that still carries its migrations ships in seconds. --no-rehearse skips it. ADVANCED: run402 deploy rehearse [<plan_id>] [--manifest <path>] rehearses without committing — from a persisted plan, or from the manifest in the current directory (plan, upload, rehearse). Manual restore points live under run402 snapshots create|list|get|restore|delete; restore is a two-step plan/confirm flow. Branch projects live under run402 branches create|list|renew|delete, default to a 7-day TTL, use sandboxed email by default, and are marked noindex; a parent with no live release yields an empty branch.
Your HTML never needs a pasted key: every Run402 host serves /_run402/config.js (window.RUN402 = { project_id, api_base, anon_key }) for the project it resolves to. run402 up also names this principal when it has none — RUN402_AGENT_NAME if your runtime declares one (it overrides an existing name), else a detected client (claude-code, codex, cursor, grok; RUN402_CLIENT=<name> declares a client with no marker of its own, checked first); when nothing is known nothing is written — so promotion credit names you; set it any time with run402 whoami --set-name <name>. result.identity always reports detected (the client seen this run) and detection: { applied, reason }, where name_already_set means a client was detected but the principal already had a name. projects provision never touches git; up scaffolds a run402 remote on the app root only, and an app root inside another repository is skipped with a create_nested_repo next action unless you pass --nested, which makes it its own nested repository (one line appended to the enclosing repository's local .git/info/exclude, nothing else touched).
Portable archives export the supported run402 Core runtime slice of a Cloud project for local Core import. This is the no-lock-in trust path, separate from allowance/spend-cap financial-risk controls.
run402 archives create <project_id> --target cloud --scope portable-runtime-v1 --auth stubs --consistency pause-writes --wait --output ./project.r402ar --json
run402 archives verify ./project.r402ar --json
run402 archives import ./project.r402ar --target core --name imported-project --env-file ./required.env --json--target names the deployment each verb talks to: create, status, and download export from Run402 Cloud (--target cloud, the default); import loads into a local Run402 Core (--target core, the default). Archive v1 excludes secret values, auth credentials, logs, billing/allowance state, Cloud operations metadata, Cloud import, and existing-project merge import. Verify is local/offline and checks integrity plus compatibility; archives remain untrusted input until Core import verifies and stages them.
The active project is sticky: run402 projects use <project_id> server-validates <project_id> and stores it as the default for subsequent <project_id>-taking subcommands, so most commands work without it. Local key material is managed separately under run402 credentials project-keys ...; that cache is never project inventory.
run402-mcpnpx -y run402-mcp # standalone testEight tools, a few kilobytes of schema in a host's context: up and deploy for the first deploy, status, whoami, doctor, docs, run, and expand_result. Everything else is a run snippet against r, the Node SDK client, executed in a QuickJS-in-WebAssembly sandbox with no filesystem, process, or network of its own. Needs Node.js 22.13 or later. Local, so it can actually pay: an x402 payment needs a signing key, so a wallet-less remote server cannot make one.
A hosted streamable-HTTP MCP server runs at https://mcp.run402.com/mcp with free discovery tools only: run402_quickstart, x402_price_check (decode any URL's x402 challenge, unpaid), and experiment_scoreboard. It never handles funds — paid capabilities (image generation, deploys, payments) require the local server below, which holds your wallet. Registry entry com.run402/mcp lists both (packages[] npm + remotes[]). The remote itself runs as a run402 function — the platform hosting its own MCP server.
Stdio MCP transports must keep stdout reserved for JSON-RPC. Use the package bin (npx -y run402-mcp) or node dist/index.js from a built checkout. If a host insists on npm start, set npm_config_loglevel=silent; npm's lifecycle banner is stdout and otherwise appears as non-JSON prelude. The repo .npmrc and Docker image set this for source/container hosts.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"run402": { "command": "npx", "args": ["-y", "run402-mcp"] }
}
}Add to .cursor/mcp.json:
{
"mcpServers": {
"run402": { "command": "npx", "args": ["-y", "run402-mcp"] }
}
}Add to your Cline MCP settings:
{
"mcpServers": {
"run402": { "command": "npx", "args": ["-y", "run402-mcp"] }
}
}claude mcp add run402 -- npx -y run402-mcpcp -r openclaw ~/.openclaw/skills/run402
cd ~/.openclaw/skills/run402/scripts && npm installEach script re-exports from cli/lib/*.mjs: the OpenClaw command surface is identical to the CLI command surface by construction. See openclaw/README.md.
Tool | What it does |
| The first deploy: any missing setup (wallet, tier, project, workspace link), then the deploy. Returns the |
| Applies a ReleaseSpec to a project ( |
|
|
|
|
|
|
| The SDK reference and the |
| Runs a TypeScript snippet against the SDK in a sandbox; returns the value, the captured logs, and the SDK calls it made. |
| Pages a stored result: a |
A snippet is the body of an async function; the value of its last expression is the result:
{ "code": "const { projects } = await r.projects.list();\nprojects.filter((p) => !p.site_url).map((p) => p.id)" }The result is { status, value, value_ref, shown, total, logs, logs_ref, calls, duration_ms, wallet, error? }: a large value is stored whole by item (an array's elements, a result's rows) and its leading whole items arrive in value_window, including in structuredContent (expand_result pages the rest by item), calls[] lists every SDK call with its outcome, and a timeout (60 s by default, 300 s at most) still lists the calls that completed. An SDK error passes through with its own code and next_actions.
Structured results. Every tool also returns its result as structuredContent under a declared outputSchema, so a host reads fields instead of parsing text. The object has status: "ok" | "error"; the fixed tools put the SDK object under result, and every error carries error.code, error.message, and error.next_actions. The fenced JSON in the text is the same object.
One-time secrets stay in the CLI. An operation that returns or consumes a one-time secret (minting or rotating a grant key, a Handoff or Invite Key, a Room Invite Key, provisioning a project or rotating its credentials, a project token, creating, importing, or exporting a wallet, the Lightning pairing) refuses inside run with SECRET_REQUIRES_CLI and one next action, { "type": "run_cli_command", "command": "run402 …" }, naming the exact command to hand the person. The refusal is in the SDK method itself, before any request, so nothing secret reaches a result.
Full reference: llms-mcp.txt.
Variable | Default | Purpose |
|
| API base URL (override for staging) |
|
| Local credential storage base directory (named wallets live under |
|
| Active named wallet (profile). Overridden by |
|
| Custom wallet file path |
| (unset) | A grant-key bearer from |
Local state lives at:
profile state.json: active project pointer and profile state
profile credentials/project-keys.v1.json (0600): local anon/service key cache for explicit credential-required operations
~/.config/run402/wallet.json (0600): wallet for x402 / MPP signing
Legacy projects.json files are one-way migration input only. anon_key and service_key have no expiry; lease enforcement happens server-side. Inspect cache state with run402 credentials project-keys status --project <project_id> and export secrets only with run402 credentials project-keys export --project <project_id> --reveal.
npm run build # builds core/, sdk/, then the MCP server
npm test # SKILL + sync + unit tests
npm run test:e2e # builds generated CLI SDK mirrors, then runs CLI end-to-end tests
npm run test:sync # checks MCP/CLI/OpenClaw/SDK stay in sync
npm run test:skill # validates SKILL.md frontmatter + bodyArchitecture: every tool / subcommand / skill script is a thin shim over an @run402/sdk call. core/ holds Node-only filesystem primitives (keystore, wallet, SIWE signing) wrapped by the SDK's Node provider. See CLAUDE.md for the full layout.
Web: https://run402.com
Self-host backend (run402 Core): https://github.com/kychee-com/run402-core
API docs (HTTP): https://run402.com/llms.txt · https://run402.com/openapi.json
CLI docs: https://docs.run402.com/llms-cli.txt (index + fetchable slices; https://docs.run402.com/llms-cli-full.txt for the whole reference)
Status: https://api.run402.com/status
Health: https://api.run402.com/health
MIT for this repo (the agent surfaces: SDK, CLI, MCP server, Astro integration, OpenClaw skill). The full backend, run402-core, is Apache-2.0.
Accept an incoming WALLET transfer (v1.93+). Your wallet must equal the transfer's to_wallet. The accept transaction atomically: (a) flips ownership to your wallet, (b) revokes the previous owner's CI bindings on the project, (c) enqueues notifications to both parties, (d) stamps a persistent secrets_rotation_advised advisory. Secret VALUES are inherited (rotation strongly advised via set_secret for each name). GitHub repo ownership is NOT part of the transfer. Email transfers complete via claim_project_transfer, not this tool. Calls POST /agent/v1/transfers/:transfer_id/accept.
| Name | Required | Description | Default |
|---|---|---|---|
| transfer_id | Yes | WALLET transfer id to accept. Your wallet must equal the transfer's to_wallet. Atomically flips ownership, revokes the previous owner's CI bindings on the project, and stamps a `secrets_rotation_advised` advisory. (Email transfers complete via `claim_project_transfer`.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Lists four atomic effects (ownership flip, CI revocation, notifications, advisory), explains secret inheritance and GitHub ownership exclusion. Fully discloses behavior.
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?
Front-loaded with summary sentence, followed by structured list of effects, then clarifications. No redundant text. Each sentence adds necessary 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?
Covers preconditions, side effects, and exclusions. Missing return value format, but given the tool is a void-like mutation with no output schema, the description is nearly complete. Slight gap in error scenarios.
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?
Single parameter with 100% schema coverage. Description adds no additional semantic meaning beyond the schema's own parameter description, which already repeats the tool's atomic effects. 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?
Clear verb ('accept') and resource ('incoming WALLET transfer'). Distinguishes from email transfers via claim_project_transfer and from siblings like cancel_project_transfer, initiate_project_transfer. Includes endpoint and version constraint.
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: wallet must equal to_wallet. Explicitly excludes email transfers, directing to claim_project_transfer. Provides clear context for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a member to an org BY WALLET (POST /orgs/v1/:org_id/members). A brand-new wallet is provisioned as a human principal. role defaults to developer. Requires you to hold an active owner membership. (Email-first invite is a separate, not-yet-shipped flow.)
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Initial role. Defaults to `developer` when omitted. Requires you to be an active `owner`. | |
| org_id | Yes | The org id to add the member to. | |
| wallet | Yes | EVM address (or named wallet) to add. A brand-new wallet is provisioned as a `human` principal. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description carries the burden. It discloses that a brand-new wallet is provisioned as a 'human' principal and the role defaults to 'developer'. It does not mention reversibility, errors, or rate limits, but the side effect is clearly stated.
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 paragraph of four sentences, each serving a purpose: action, side effect, default, prerequisite, and alternative. 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?
For a mutation tool with no output schema, the description covers the action, prerequisite, default, and side effect. It could mention what the response indicates (e.g., success or the new member object), but this is a minor gap. The presence of list_org_members among siblings compensates partially.
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 baseline is 3. The description adds meaningful context: that 'wallet' can be an EVM address or named wallet, that a new wallet is provisioned, and that 'role' defaults to 'developer'. This exceeds mere schema repetition.
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 verb 'Add' with resource 'member to an org' is explicit. The method 'BY WALLET' and inclusion of the REST endpoint clarify the operation. It distinguishes from the email-first invite flow, differentiating from potential sibling 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?
It explicitly requires an active 'owner' membership and notes the default role. It mentions the email-invite alternative as separate and not-yet-shipped, providing context for when to use this tool. However, it does not explicitly name alternative tools or state 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.
Operator moderation action — archive a single project (sets projects.archived_at = NOW()). Independent of organization-level lifecycle: sibling projects on the same organization keep serving. No-op when the project is already archived. Platform-admin only. Calls POST /projects/v1/admin/:id/archive.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Free-text moderation reason recorded in the audit log (recommended). | |
| project_id | Yes | The project ID to archive. Platform-admin only — sets `projects.archived_at = NOW()` and takes only this project down. Sibling projects on the same organization keep serving. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses non-obvious behaviors: sets archived_at, no-op when archived, admin-only restriction. Lacks details on destruction scope or rate limits, but with no annotations, this is adequate.
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 efficiently written sentences, front-loaded with key purpose. No redundant or missing 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?
Covers all essential context for this simple mutation: side effects, no-op condition, admin requirement. No output schema needed.
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 adds value by explaining the purpose of 'reason' (audit log) and the effect of 'project_id', beyond 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?
Description clearly states 'archive a single project' with specific SQL effect, and distinguishes from sibling tools by noting independence from organization-level lifecycle.
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?
Mentions 'Platform-admin only' and no-op behavior, providing clear context. Does not explicitly list exclusions or alternatives, but the context is sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Operator un-archive — flips projects.archived_at back to NULL. In v1.57 this was narrowed: it no longer touches organization-level lifecycle. To reactivate a grace-state organization, subscribe a tier (tier_set) or enable lease-perpetual (admin_set_lease_perpetual). Platform-admin only. Calls POST /projects/v1/admin/:id/reactivate.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID to un-archive. Platform-admin only — flips `projects.archived_at` back to NULL. In v1.57 this was narrowed: it does NOT reactivate a grace-state organization. For that, subscribe a tier (`run402 tier set <tier>`) or toggle the organization-level escape hatch via `admin_set_lease_perpetual`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It reveals the mutation (archived_at to NULL), a behavior change in v1.57, and the API endpoint. However, it does not discuss idempotency or rate limits, but for a simple field flip, this is adequate.
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 primary action. Each sentence adds value: action, version constraint, alternatives. 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?
For a simple one-parameter tool with no output schema, the description covers authorization, limitations, and alternatives. Lacks example output or error cases, but overall 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 description coverage is 100%, so baseline is 3. The description adds little beyond the schema; both state the same information about the project ID. No extra semantic value.
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 un-archives a project by flipping `projects.archived_at` to NULL. It distinguishes from sibling tools like `admin_set_lease_perpetual` and `tier_set` by noting it does not handle organization-level lifecycle.
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 'Platform-admin only' and provides clear alternatives: for grace-state organizations, use `tier_set` or `admin_set_lease_perpetual` instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Toggle an organization's lease_perpetual escape hatch (v1.57+). When lease_perpetual: true, the organization never advances past active regardless of lease expiry; every project in the organization inherits the pinned state. Enabling on a grace-state organization (past_due / frozen / dormant) reactivates inline and returns reactivated: true. Platform-admin only — uses the configured allowance wallet for admin auth. Replaces the v1.56 pin_project (gateway endpoint /projects/v1/admin/:id/pin was removed in v1.57). Calls POST /orgs/v1/admin/:org_id/lease-perpetual.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The organization ID to toggle. Format: UUID. Platform-admin only — uses the configured allowance wallet for admin auth; project owners with a non-admin SIWX wallet will receive 403 admin_required. | |
| lease_perpetual | Yes | true → pin every project in the organization (organization never advances past 'active' regardless of lease expiry). false → resume normal lifecycle advancement. Enabling on a grace-state organization reactivates inline (response includes `reactivated: true`). Replaces the v1.56 per-project pin (gateway endpoint /projects/v1/admin/:id/pin was removed in v1.57). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that enabling sets lease_perpetual: true, prevents lifecycle advancement beyond active, projects inherit the state, enabling on grace-state organizations reactivates inline and returns reactivated: true, and that it uses the configured allowance wallet. It omits details like idempotency or error responses but covers essential behavioral traits.
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 moderately concise with no fluff. The first sentence clearly states the main action. It efficiently conveys the behavior, auth requirements, versioning, and API endpoint. Could be slightly more structured (e.g., bullet points) but remains 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?
Given the tool's moderate complexity, the description is fairly complete. It explains the core functionality, project inheritance, reactivation behavior, admin authentication, and the replacement of the old endpoint. With no output schema, it mentions the reactivated: true field in responses. It lacks information about potential errors or pagination but covers the necessary context for an agent to use it 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 both parameters well-described. The tool description adds conceptual context ('escape hatch', 'pinned state', 'v1.57+') but does not significantly extend beyond the schema descriptions for the parameters themselves. The schema already explains format, admin requirements, and effects.
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 action: 'Toggle an organization's `lease_perpetual` escape hatch'. It specifies the resource (organization), the effect (pinning state, inheritance, reactivation), and distinguishes itself from the deprecated v1.56 pin_project. Among siblings like admin_archive_project and admin_reactivate_project, this tool's unique purpose is well-defined.
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 clear context on when to use the tool: for toggling the lease_perpetual flag on an organization. It specifies that it is platform-admin only using an allowance wallet, and that it replaces the older pin_project endpoint. However, it does not explicitly state when not to use it or list alternatives for similar admin tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run content moderation on text. Returns flagged status and category scores. Free for all projects, requires service key.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text content to check for moderation | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility. It discloses that the tool is free and requires a service key, but does not describe whether it is read-only, rate limits, or other behavioral traits. The return value description is minimal.
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 that front-load the purpose and then add practical info (free, service key). 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 simplicity of the tool (2 required params, no output schema), the description covers purpose, return values, pricing, and auth. Lacks detail on moderation categories or text limits, but is largely 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% with descriptions already provided for both parameters. The tool description adds no additional parameter-level 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 clearly states the tool's purpose ('Run content moderation on text') and specifies output ('Returns flagged status and category scores'). It distinguishes from sibling tools like ai_translate by focusing on moderation rather than translation.
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 checking text content but does not provide explicit guidance on when to use vs. alternatives or when not to use. No exclusions or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Translate text to a target language. Requires service key and active AI Translation add-on. Supports optional source language and context hint.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Target language (ISO 639-1 code, e.g. 'es', 'ja', 'fr') | |
| from | No | Source language (ISO 639-1 code). Auto-detected if omitted | |
| text | Yes | Text to translate (max 10,000 characters) | |
| context | No | Context hint for tone/register (max 200 chars, e.g. 'formal business email') | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the need for a service key and active add-on, and mentions optional parameters. However, it lacks detail on error behavior, rate limits, or return format.
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 covering purpose, requirements, and options. No extraneous text, clear and front-loaded. Slightly over-simplified 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?
Given no output schema, the description omits return value details. It also does not mention character limits (though present in schema) or error cases. It covers core purpose but not enough for complete agent guidance.
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 already documented. The description adds minimal value by noting 'optional source language and context hint,' which is redundant with schema descriptions. 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 the action ('Translate text to a target language') and the resource (text). It is unique among siblings, with no other translation tool, so no ambiguity.
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 no guidance on when to use this tool versus alternatives. It only mentions prerequisites (service key, add-on) but does not specify contexts where translation is appropriate or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get AI translation usage for the current billing period — used words, quota, and remaining balance.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It discloses the operation is a read ('Get') and the scope, but does not mention authorization needs, rate limits, idempotency, or any side effects. Minimal transparency beyond the basic purpose.
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 front-loads the verb and resource, efficiently conveying purpose and output. No fluff or 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?
For a simple read tool with one parameter and no output schema, the description covers purpose, scope, and key output fields. It does not detail return format or pagination, but that is likely unnecessary for a quota query. The lack of annotations is partially mitigated by the clear description.
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 for the only parameter (project_id) is 100% with a description. The tool description adds value by clarifying the output (used words, quota, remaining balance) and temporal scope (current billing period), which are 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 'Get AI translation usage' with specific outputs: used words, quota, remaining balance. It distinguishes from siblings like 'get_usage' and 'allowance_status' by specifying AI translation context.
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 mentions 'for the current billing period' but does not provide explicit guidance on when to use this tool vs alternatives like 'get_usage' or 'allowance_status'. It lacks when-not-to-use or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new local agent allowance (Base Sepolia testnet). Generates a private key and derives the Ethereum address. Saved to ~/.config/run402/allowance.json.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the tool's behavior: it creates a new allowance, generates a private key, derives an address, and writes to a specific file. This is transparent for a simple creation action, though it could mention any implicit permissions or 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 extremely concise with two well-structured sentences. It front-loads the primary purpose and then provides key details. No unnecessary 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 simplicity (no parameters, no output schema), the description covers all necessary information: what it does, what it creates, and where it saves. No gaps.
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 tool has zero parameters, and the input schema coverage is trivially 100%. The description adds no parameter information, which is acceptable per the rubric baseline of 4 for no 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 creates a new local agent allowance on Base Sepolia testnet. It specifies the actions: generating a private key, deriving an Ethereum address, and saving to a config file. This distinguishes it from sibling tools like allowance_export and allowance_status.
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 no guidance on when to use this tool versus alternatives. It does not mention conditions, prerequisites, or when not to use it. Given the presence of related sibling tools, explicit usage context would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the local agent allowance address. Safe to share publicly. This is also the MAINNET on-ramp: to pay with real USDC on Base mainnet, send USDC to this address — request_faucet only funds Base Sepolia testnet, which cannot settle a real payment.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the address is safe to share publicly and clarifies the mainnet vs. testnet distinction. This adds useful behavioral context, though it doesn't explicitly state there are no side effects or describe return format in detail, which would push it to 5.
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 core purpose, and every sentence earns its place: purpose, safety, and mainnet on-ramp context. There is no redundancy or 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?
For a zero-parameter tool with no output schema, the description is complete. It states what it does, why it's safe, the primary use case (mainnet payments), and warns against a common pitfall with request_faucet. No additional context is needed for an agent to use it 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?
The tool has 0 parameters and the schema is empty with 100% coverage, so the baseline is 4. The description doesn't need to add parameter information because none exists, and it doesn't attempt to invent any.
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 exports the local agent allowance address with a specific verb and resource. It further distinguishes itself by identifying the mainnet on-ramp use case, separating it from related tools like allowance_status and allowance_create.
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 provides usage context by explaining when to use this tool (for real USDC on Base mainnet) and contrasts it with request_faucet, which only funds testnet and cannot settle real payments. This gives clear guidance on when 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.
Check local agent allowance status — address, network, and funding status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states 'Check', implying a read operation, but lacks details on side effects, auth requirements, error scenarios, 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?
The description is one sentence with 10 words, front-loading the purpose and key details. No extraneous content.
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 three key aspects of the return. It is adequate for a simple check tool, though it omits potential output format or error handling.
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?
This tool has zero parameters, so baseline is 4. The description adds meaning by specifying what aspects are checked (address, network, funding status), which is useful beyond the empty 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 the specific verb 'Check' and resource 'local agent allowance status', listing three aspects: address, network, and funding status. It clearly distinguishes from sibling tools like allowance_create and allowance_export.
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 when needing allowance status, but provides no explicit when-to-use, when-not-to-use, or alternatives. No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a declarative authorization manifest to a project (POST /projects/v1/admin/:id/expose). The manifest describes the full authorization surface: tables (with policy, owner_column, force_owner_on_insert, i_understand_this_is_unrestricted, custom_sql), views (with base, select, filter), and rpcs (with signature, grant_to). Convergent: applying the same manifest twice is a no-op; items dropped between applies have their policies/grants/triggers/views revoked. Tables are dark by default — any table not declared with expose:true is unreachable via anon/authenticated.
| Name | Required | Description | Default |
|---|---|---|---|
| manifest | Yes | Full authorization manifest. Convergent: applying twice is a no-op; items removed between applies are dropped. Tables are dark by default — any table not listed with expose:true is unreachable via anon/authenticated. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: convergent (idempotent), tables dark by default, revocation of dropped items. No annotations provided, so description carries full burden and meets it well.
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?
Well-structured with clear front-loading of action. Each sentence adds value, though slightly verbose. No redundant content.
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 manifest structure, convergence, and default behavior. Lacks explanation of return values, error conditions, or success/failure outcomes. Adequate for a mutation tool but could be more complete given 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 description coverage is 100%, so baseline is 3. Description summarizes manifest structure but does not add new parameter syntax or format details 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?
Clearly states the verb 'apply' and the resource 'declarative authorization manifest to a project', includes the HTTP endpoint. Distinguishes from sibling tools like 'validate_manifest' (validation) and 'get_expose' (retrieval) by focusing on application.
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?
Implies usage for applying manifests but does not explicitly mention alternatives or when not to use. The convergence note ('applying twice is a no-op') provides guidance but no direct comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plan or run the canonical app-aware run402 up workflow from a local path or repo URL. Delegates to the SDK and returns the shared app-up result envelope with graph steps, resources, diagnostics, and next_actions.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Workspace directory to inspect when source is omitted. | |
| yes | No | Approve non-interactive prerequisite, spend, and local-write prompts. | |
| name | No | Project/app instance name, for example kysigned2. | |
| tier | No | Bootstrap tier if account readiness is needed. | |
| source | No | Local app directory or public Git repository URL. Defaults to the current directory. | |
| dry_run | No | Plan only. No gateway mutation, build execution, release commit, local link write, or prune. | |
| manifest | No | Explicit manifest path. Defaults to run402.json, then advanced release-only manifests. | |
| build_mode | No | Override app build mode. | |
| project_id | No | Existing project id to install into. | |
| allow_prune | No | Approve destructive managed-resource prune steps. | |
| max_spend_usd | No | Maximum spend app_up may approve for readiness steps. | |
| idempotency_key | No | Root idempotency key for resumable app-up graph mutations. | |
| allow_shell_build | No | Approve shell-string build commands after review. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It mentions delegation to the SDK and a result envelope, but does not disclose side effects, auth requirements, or what 'plan only' entails (the dry_run parameter covers that in schema, but not in the main description). Lack of transparency on mutation behavior is a significant gap.
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 (55 words), front-loading the core action and following with delegation details. Every sentence adds value 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?
For a tool with 13 parameters and no output schema or annotations, the description provides a reasonable high-level overview but omits details on SDK return structure, step lifecycle, and how parameters like dry_run affect behavior. Adequate but not thorough.
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 each parameter has a description. The main description adds value by explaining the high-level workflow and the return envelope ('graph steps, resources, diagnostics, next_actions'), which compensates for the lack of an output schema. Baseline 3 plus extra context.
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 plans or runs the app-aware workflow, specifying the resource ('run402 up') and source ('local path or repo URL'). It distinguishes from siblings by naming the canonical workflow, though it could explicitly differentiate from related tools like '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?
The description implies usage for planning or running the up workflow, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it suggest alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a blob to a local file path. Writes bytes directly to disk (no context-window bloat). Returns size + SHA-256 header (if the blob has one stored).
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Blob key to download | |
| project_id | Yes | Project ID | |
| output_path | Yes | Local filesystem path to write the bytes to. Parent directories will be created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses that bytes are written directly to disk and that return includes size and SHA-256 header (if stored). This adds value beyond the input schema, though it does not mention file overwrite behavior or error conditions.
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 sentences: first states action, second explains return. Every word adds value with 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?
For a simple download tool with 3 parameters and no output schema, the description covers purpose, behavior, and return values. However, it lacks information on error handling (e.g., missing key) and overwrite behavior, leaving minor gaps.
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 already provides descriptions for all three parameters (100% coverage). The description adds no further detail about parameters, so it meets the baseline but does not exceed it.
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 explicitly states 'Download a blob to a local file path', with a specific verb and resource. It differentiates from sibling tools like assets_ls, assets_put, assets_rm, assets_sign by focusing on download.
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?
Description provides clear context by mentioning 'no context-window bloat' as a benefit, implying use when local storage is preferred. However, it does not explicitly state when not to use or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List blobs in a project with optional prefix filter over a flat key namespace. Supports pagination via cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | v1.50: result ordering. Default 'key:asc' (legacy bare-key cursor). 'createdAt:*' variants use a base64url JSON cursor. | |
| limit | No | Max results (default 100, max 1000) | |
| cursor | No | Pagination cursor from a previous response's next_cursor. v1.50: cursor is sort-pinned — reuse with a different `sort` returns 400 INVALID_CURSOR_FOR_SORT. | |
| filter | No | v1.50: media-picker filter. Unknown keys are rejected with INVALID_FILTER_KEY before any HTTP call. | |
| prefix | No | Filter: only return blobs whose key starts with this prefix | |
| project_id | Yes | Project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions listing, prefix filtering, and pagination, but does not disclose other behavioral traits like whether it is read-only, auth requirements, or rate limits. The description is adequate but minimal.
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 consists of two concise sentences with no wasted words. It front-loads the main purpose and efficiently communicates key features.
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 tool has a complex input schema (nested filter object) and no output schema. The description does not explain the response format, such as the structure of returned blobs or the pagination cursor details. This leaves significant gaps 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?
The input schema has 100% description coverage, so the schema already documents each parameter. The description adds value by linking 'optional prefix filter' to the prefix parameter and 'pagination via cursor' to cursor/limit, helping to understand their roles.
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 blobs in a project with optional prefix filtering and pagination. It uses specific verbs ('List') and resources ('blobs'), and the context distinguishes it from sibling tools like assets_get, assets_put, and assets_rm.
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 explains what the tool does but does not provide explicit guidance on when to use it versus alternatives, nor does it mention when not to use it. It implies use for listing blobs, but lacks comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a blob (file or inline content) to project storage via direct-to-S3. Accepts local_path (any size up to 5 TiB) or content (≤ 1 MB inline). Public blobs get a CDN URL; private blobs require authenticated reads. Use immutable: true to produce a content-addressed URL that never needs cache invalidation. For image uploads (jpeg/png/webp/heic/heif), the gateway also returns width_px/height_px/blurhash/display_url and a variants map (thumb 320w, medium 800w, large 1920w WebP — plus display_jpeg for HEIC sources) so apps can render responsive thumbnails without re-encoding client-side. See the SDK docs for the full AssetRef shape.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Destination key (path in the project's blob namespace). No leading slash. Example: 'images/logo.png' or 'circuits/v1.zkey'. | |
| content | No | Inline content to upload (UTF-8 string). For small blobs ≤ 1 MB. Mutually exclusive with `local_path`. | |
| metadata | No | v1.50: caller-provided flat metadata stored alongside the asset. Object with string / number / boolean / string[] leaves; ≤4 KB serialized. Nested objects rejected with INVALID_ASSET_METADATA (HTTP 400). | |
| immutable | No | When true, the returned URL includes a content-hash suffix so overwrites produce distinct URLs. CLI auto-computes sha256. | |
| local_path | No | Path to a local file to upload. Mutually exclusive with `content`. | |
| project_id | Yes | Project ID | |
| visibility | No | Default: public. Public blobs get a CDN URL; private blobs require authenticated reads. | |
| exif_policy | No | v1.50: EXIF retention policy for image uploads. Default 'keep'. 'strip' discards EXIF from the stored bytes and the image_exif response field. | |
| content_type | No | MIME type (auto-detected from file extension if omitted). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behaviors: direct-to-S3, public/private visibility, immutable URLs, size limits (5 TiB vs 1 MB), image variant generation, EXIF policy, and auto-detected content type. However, it does not mention error cases or conflict behavior (e.g., overwrite vs. fail).
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 paragraph with multiple details, not front-loaded. It is adequate but could be more concise and structured (e.g., using bullet points for image handling). Some redundancy with schema descriptions.
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 covers many aspects (purpose, size, visibility, immutable, image processing) but omits the return shape (defers to SDK docs), error handling, and conflict semantics. For a complex mutation with 9 parameters, this is a notable gap.
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%, baseline 3. The description adds context beyond schema: size limits for local_path vs content, immutable URL semantics, image processing details, and EXIF policy explanation. This adds significant value.
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 'Upload a blob (file or inline content) to project storage via direct-to-S3', specifying the verb and resource. It distinguishes from sibling tools like assets_get (download) and assets_ls (list).
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 does not explicitly state when to use this tool versus alternatives. It provides details on behavior but lacks guidance on exclusions or context for choosing over other methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a blob from project storage and decrement the project's storage_bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Blob key to delete | |
| project_id | Yes | Project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive action and side effect, but no annotations are present. Lacks details on permanence, permissions, or error handling for missing keys.
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 redundant information, front-loaded action and side effect.
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?
Adequately states action and side effect but lacks behavior on missing keys or error states. For a deletion tool, more context on reversibility would be beneficial.
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 fully describes both parameters with 100% coverage. Description adds no additional semantic value beyond what is 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?
Description clearly states 'delete a blob' and specifies the side effect 'decrement storage_bytes'. It distinguishes from sibling asset tools (assets_get, assets_ls, assets_put, assets_sign) by indicating a destructive operation.
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, no prerequisites or conditions for deletion provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a time-boxed S3 presigned GET URL for a blob. Use this to share a private blob externally without exposing your apikey. Default TTL 1 hour, max 7 days.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Blob key to sign a GET URL for | |
| project_id | Yes | Project ID | |
| ttl_seconds | No | URL lifetime in seconds (60 – 604 800, default 3600) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the time-bound nature, default TTL (1 hour), maximum (7 days), and that it is a presigned GET URL (read-only). It doesn't specify error behavior if blob is missing, but the key behavioral traits are covered.
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 sentences: the first states the core functionality, the second provides usage guidance and default/max values. No wasted words, front-loaded with essential 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?
For a simple 3-parameter tool with no output schema, the description is largely complete. It explains purpose, usage, and key parameter constraints. It could mention that the URL is returned, but that is implied by 'generate... URL'.
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 parameter descriptions. The description adds context about default TTL and max TTL, but this is already partially covered in the schema. Baseline 3 is appropriate as the description adds marginal value 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 generates a time-boxed S3 presigned GET URL for a blob, with a specific use case (external sharing without exposing API key). It distinguishes itself from sibling assets tools like assets_get, assets_ls, etc.
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 for sharing private blobs externally without exposing the apikey. It provides clear context but does not explicitly exclude cases where alternative tools (e.g., assets_get) might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update project auth settings: allow_password_set, preferred_sign_in_method, public_signup, and require_passkey_for_project_admin. Requires service_key.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID | |
| public_signup | No | Public signup policy. | |
| allow_password_set | No | Allow passwordless users (magic link / OAuth) to set a password. Default: false. | |
| allowed_email_domains | No | Restrict hosted Google sign-in to these email domains, enforced at token issuance. [] or omitted = unrestricted; pass [] to clear. Normalized + domain-validated server-side. | |
| preferred_sign_in_method | No | Project UI hint for the preferred sign-in method. | |
| require_passkey_for_project_admin | No | Require eligible passkey login for project_admin sessions. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must convey behavioral traits. It indicates a write operation ('Update') and a prerequisite (service_key), but does not disclose side effects (e.g., whether changes affect active sessions), idempotency, or error scenarios. The description lacks depth for a mutation tool.
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 two sentences. The first sentence lists the action and fields, the second mentions a requirement. While efficient, it could be better structured with bullet points or separate lines for readability.
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 6 parameters, no output schema, and no annotations, the description should provide more context about expected behavior, return values, and side effects. It only covers the basic action and a single requirement, leaving gaps for an agent to correctly invoke the 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 description coverage is 100%, so the schema already documents all parameters. The description adds minimal value by listing 4 of 6 parameters and noting a default (allow_password_set default: false), but omits 'allowed_email_domains' and 'project_id'. The description does not compensate for schema completeness.
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 'Update' and the resource 'project auth settings', listing four specific fields. This distinguishes it from sibling tools like create_auth_user which manage users, or set_user_password which is per-user. However, it could be more explicit about the scope (project-level configuration).
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 mentions a requirement ('Requires service_key'), which is a basic usage guideline. However, it does not specify when to use this tool versus alternatives, such as when to update individual user settings instead. No exclusions or conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
View billing ledger history for the agent's allowance wallet. The wallet is resolved to its organization over SIWX (signed automatically); a wallet not linked to yours requires an admin key.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entries to return (default: 20) | |
| wallet | Yes | Wallet address (0x...) to get billing history for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It mentions that the wallet is resolved to its organization over SIWX and that a wallet not linked requires an admin key, which is useful. However, it does not disclose whether the operation is read-only (implied by 'View'), whether results are paginated (despite the 'limit' parameter suggesting pagination), or what the response structure contains.
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-loaded with the purpose in the first sentence. The second sentence adds essential behavioral context without waste. Every part earns its place, making it highly concise and 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?
For a simple tool with no output schema, the description covers purpose and key behavioral context (resolution, admin key). However, it omits details about the returned data structure (e.g., what fields are in the billing history) and does not mention that results may be paginated despite the 'limit' parameter. Given the simplicity, it is adequate but not fully 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?
The input schema covers both parameters with descriptions, achieving 100% coverage. The tool's description does not add new semantic meaning beyond the schema; it only provides context about wallet resolution. Per guidelines, baseline is 3 when schema coverage is high, so this score 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 'View billing ledger history' with the specific resource 'agent's allowance wallet'. This gives a clear verb and resource. However, it does not explicitly differentiate from similar sibling tools like 'allowance_status' or 'check_balance', which could lead to confusion about when to use this tool over others.
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 some usage context, such as wallet resolution over SIWX and the need for an admin key if the wallet is not linked. However, it lacks explicit guidance on when to use this tool versus alternatives like 'allowance_status' or 'get_usage'. No alternatives are named, leaving the agent to infer the correct usage scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse public apps available for forking. Optionally filter by tags.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tags to filter by (e.g. ['auth', 'rls']) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the function (browse) but does not specify read-only nature, pagination, or any side effects. The description lacks transparency about what the tool does beyond the action.
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, concise and front-loaded with the core action. No unnecessary words or 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?
For a simple tool with one optional parameter and no output schema, the description covers the essential purpose and filtering capability. It could mention that a list of apps is returned, but is otherwise adequate.
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 schema covers 100% of the parameter (tags) with its own description. The tool description does not add additional meaning beyond the schema, so the 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?
Description clearly states the action ('browse public apps') and the specific purpose (available for forking), with optional filtering by tags. This distinguishes it from sibling tools like 'fork_app' or 'get_app'.
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. No mention of scenarios where browsing is appropriate or when other tools (e.g., 'get_app' for a specific app) should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a scheduled/queued durable function run when it has not completed yet.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | Function run id, fnrun_... | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States the precondition (run not completed) but lacks info on side effects, required permissions, idempotency, or what happens after cancellation. No annotations provided to supplement.
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, front-loaded with key action and condition. No unnecessary 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?
Adequate for a simple cancellation action. Covers purpose and precondition. Could be enhanced with return value or error conditions, but not required given no output schema.
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 both parameters documented. Description adds no additional meaning beyond the schema definitions.
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 verb 'cancel', the resource 'scheduled/queued durable function run', and a condition 'when it has not completed yet'. Distinguishes from sibling tools like 'redrive_function_run' or 'create_function_run'.
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?
Implies usage when the function run is scheduled/queued and not completed. However, it does not explicitly state when not to use it or mention alternative tools for completed runs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a pending project transfer of any kind (v1.93+). You must be authorized for the row's kind (a wallet signing party, an owner/admin of the offering org, or the addressed-email principal). Already-accepted/cancelled/expired transfers return 409 TRANSFER_ALREADY_PROCESSED. Calls POST /agent/v1/transfers/:transfer_id/cancel.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Optional free-text cancellation reason recorded on the audit row. | |
| transfer_id | Yes | Transfer id to cancel. You must be authorized for the row's kind (a wallet signing party, or an owner/admin of the offering org / the addressed-email principal). Kind-agnostic. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses authorization, error handling, and the HTTP endpoint. It does not detail side effects or reversibility, but covers key behavioral aspects.
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 concise sentences, front-loaded with the primary action. No unnecessary words, 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 no output schema and related sibling tools, the description covers purpose, auth, error conditions, and endpoint. It does not explain post-cancellation behavior or notification, but is adequate for the tool's simplicity.
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 meaning beyond the schema, as the parameter descriptions already exist and are not enriched further.
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 ('Cancel') and the resource ('pending project transfer'), including a version requirement. It distinguishes from siblings like 'accept_project_transfer' and 'claim_project_transfer' by specifying cancellation.
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 specifies authorization requirements and error conditions (409 for already-processed transfers). It lacks explicit comparison to siblings but provides sufficient context for when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the organization balance for the agent's allowance wallet — available and held funds. The wallet is resolved to its organization over SIWX (signed automatically); reading a wallet that is not linked to yours requires an admin key.
| Name | Required | Description | Default |
|---|---|---|---|
| wallet | Yes | Wallet address (0x...) to check billing balance for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses key behaviors: wallet resolution via SIWX (signed automatically), and the admin key requirement for non-linked wallets. However, it does not mention rate limits, side effects, or whether it is purely read-only (though implied).
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-loaded with the primary purpose. Every word adds value, with no redundancy or filler. It efficiently conveys the core function and an important behavioral nuance.
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 (one parameter, no output schema), the description covers the main concepts: purpose, wallet resolution, and access control. However, it omits the return format (e.g., what 'available and held funds' looks like), which would improve completeness.
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 schema provides 100% coverage with a basic description. The tool description adds significant context: wallet resolution mechanism and admin key requirement, which go beyond the schema. This extra information helps understand parameter implications.
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 the action ('Check'), the resource ('organization balance for the agent's allowance wallet'), and the scope ('available and held funds'), making the purpose specific and clear. It implicitly distinguishes from sibling tools like 'allowance_status' by focusing on balance checking.
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 no guidance on when to use this tool versus alternatives. It mentions a condition (admin key for other wallets) but does not explicitly state use cases, prerequisites, or exclusions. No sibling differentiation is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a GitHub Actions CI/OIDC deploy binding by sending a locally signed delegation to the SDK. This MCP wrapper does not sign or broaden authority; the signed delegation defines the repository/branch or environment, allowed events/actions, and optional route_scopes. Without route_scopes, CI cannot deploy route declarations.
| Name | Required | Description | Default |
|---|---|---|---|
| nonce | Yes | Lowercase hex nonce included in the signed delegation. | |
| provider | No | CI provider. V1 supports only github-actions; omitted defaults to github-actions. | |
| expires_at | No | Optional ISO timestamp when this binding expires. | |
| project_id | Yes | Project ID the CI binding may deploy to. | |
| route_scopes | No | Optional route delegation scopes, normalized by the SDK. Use exact paths like /admin or final wildcard prefixes like /api/*. Omit or pass [] for no CI route authority. | |
| subject_match | Yes | GitHub Actions OIDC subject match, e.g. repo:owner/repo:ref:refs/heads/main. | |
| allowed_events | Yes | Allowed GitHub event names, typically push and workflow_dispatch. | |
| allowed_actions | Yes | Allowed CI actions. V1 supports only deploy. | |
| signed_delegation | Yes | Base64 SIGN-IN-WITH-X delegation signed locally by the allowance wallet. This MCP tool does not sign; it only sends the signed delegation to the SDK. | |
| github_repository_id | No | Numeric GitHub repository id to pin the binding to, or null if absent. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond what annotations (which are absent) would provide. It explicitly states that the tool does not sign or broaden authority, and clarifies that route_scopes are required for route deployment. It could be improved by mentioning what happens on success or error, but overall it is transparent about the tool's limitations.
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 (3 sentences) and front-loaded with the purpose. Every sentence adds essential information without redundancy. The structure is logical: purpose, behavioral note, and a specific caveat about route_scopes.
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 high parameter count (10) and no output schema or annotations, the description covers the core behavioral aspects well. It explains the delegation flow and parameter importance. However, it lacks any indication of the return value or error conditions, which would be helpful for an AI agent to understand the tool's outcome.
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, the baseline is 3. The description adds value by explaining the role of the signed delegation (locally signed, not signed by the tool) and emphasizing the significance of route_scopes for route deployment. This additional context helps an AI agent understand parameter nuances 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: creating a GitHub Actions CI/OIDC deploy binding. It uses a specific verb ('Create') and names the resource ('GitHub Actions CI/OIDC deploy binding'). It distinguishes itself from sibling CI tools (get, list, revoke) by specifying it is a creation operation.
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 clear context on when to use the tool (to create a binding) and includes important usage notes: the signed delegation must be created locally, and without route_scopes the CI cannot deploy route declarations. However, it does not explicitly list alternatives or situations where this tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one CI/OIDC deploy binding by id, including its subject, allowed events/actions, repository id, revocation state, and route_scopes.
| Name | Required | Description | Default |
|---|---|---|---|
| binding_id | Yes | CI binding id, e.g. cib_... |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It implies a read operation (get), but does not explicitly state safety, side effects, or authentication needs. Acceptable for a simple getter.
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 efficiently conveys purpose and scope, with no wasted words. Information 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 no output schema, description lists key return fields (subject, events, repo id, etc.), making it useful. Could mention error handling, but not required.
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 100% of the single parameter (binding_id). Description adds return field details but no additional parameter meaning. 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 action 'Get one CI/OIDC deploy binding by id' and lists specific fields returned, distinguishing it from sibling tools like ci_list_bindings and ci_create_binding.
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 when a single binding ID is known, but lacks explicit when-not or alternative conditions. Sibling tool names (ci_list_bindings) provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List CI/OIDC deploy bindings for a project, including route_scopes when delegated. Use this to inspect which GitHub Actions subjects can deploy before editing bindings.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID whose CI bindings should be listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It mentions that route_scopes are included when delegated, which is a behavioral detail beyond a simple list. However, it doesn't disclose any side effects, authentication needs, or performance characteristics. It adequately describes a read operation without 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 consists of two sentences: the first states the action, and the second provides usage context. No unnecessary words. It is well-structured and front-loaded with the primary 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 simplicity of the tool (one parameter, no output schema), the description is largely complete. It explains what is listed (including route_scopes when delegated) and when to use it. The lack of output schema is mitigated by the clear behavioral description.
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 only parameter, project_id, is fully described in the schema with clear meaning. The description adds no additional information beyond what the schema provides. With 100% schema coverage, 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 'List', the resource 'CI/OIDC deploy bindings', and scope 'for a project, including route_scopes when delegated'. This distinguishes it from sibling tools like ci_create_binding, ci_get_binding, and ci_revoke_binding.
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 usage context: 'Use this to inspect which GitHub Actions subjects can deploy before editing bindings.' While it doesn't explicitly state when not to use it, the context implies it's for inspection before editing, and sibling tool names provide differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke one CI/OIDC deploy binding. Revocation stops future CI gateway requests, but does not undo already deployed releases or rotate secrets.
| Name | Required | Description | Default |
|---|---|---|---|
| binding_id | Yes | CI binding id to revoke. Revocation stops future CI requests only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavioral traits: stops future requests only, does not affect past releases or secrets. No annotations provided, so description carries full burden; it does so adequately.
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 sentences: first states action, second clarifies scope and limitations. No unnecessary 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?
For a simple revocation tool with one parameter and no output schema, description covers purpose, effect, and limitations completely.
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 for binding_id already provides meaning (CI binding id to revoke). Tool description repeats this without adding new details. Baseline 3 for 100% schema coverage.
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 action (revoke) and resource (CI/OIDC deploy binding). Distinct from siblings like ci_create_binding, ci_get_binding, ci_list_bindings.
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?
Describes effect (stops future requests) and limitations (does not undo releases or rotate secrets). Implicitly tells when to use; could explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim an incoming EMAIL transfer into an org (v1.93+) — the email analog of accept_project_transfer. The transfer's addressed email must match your verified email. Provide org_id to claim into an org you own/admin, or omit to create a new org. Atomically flips ownership and returns the new owner's project keys (persisted to the local keystore, symmetric with accept) so you can operate the project immediately. Calls POST /agent/v1/transfers/:transfer_id/claim.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | No | Organization to claim the project into (you must own/admin it). Omit to claim into a brand-new org. | |
| transfer_id | Yes | EMAIL transfer id to claim. The transfer's addressed email must match your verified email. The email analog of `accept_project_transfer`. | |
| accept_retained_collaborator | No | Accept the sender's v1.91 retained-`developer`-membership offer (see the preview's retain_collaborator). Omit (the default) for a full severance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully carries the burden. It discloses atomic ownership flip, return of project keys, persistence to local keystore, and the symmetric behavior with `accept`. Additionally, it mentions the API endpoint. All behavioral traits are transparent.
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?
Concise paragraph of ~100 words with front-loaded purpose, then conditions, then behavioral details. Every sentence adds value 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?
For a tool of this complexity (email transfer claim, org handling, key persistence), the description covers all essential aspects: condition, org options, atomic behavior, return value, and API endpoint. No output schema, but return value is mentioned.
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 significant extra meaning for parameters beyond what the schema already provides. It only briefly mentions `org_id` context but otherwise replicates schema info.
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 verb 'Claim' and resource 'incoming EMAIL transfer', distinguishing it from `accept_project_transfer` by specifying it's the email analog. The scope and purpose are unmistakable.
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 explicit conditions for use (email match, org ownership) and explains when to provide or omit `org_id`. It contrasts with `accept_project_transfer` but does not discuss when to avoid using the tool or list alternative tools beyond the analog.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim a custom subdomain (e.g. myapp.run402.com) and point it at an existing deployment. Free, requires service_key auth.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Custom subdomain name (e.g. 'myapp' → myapp.run402.com). 3-63 chars, lowercase alphanumeric + hyphens. | |
| project_id | No | Optional project ID for ownership tracking. Uses stored service_key for auth. | |
| deployment_id | Yes | Deployment ID to point this subdomain at (e.g. 'dpl_1709337600000_a1b2c3') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It only states cost and auth requirements, but fails to disclose behavioral traits like idempotency, uniqueness constraints, or consequences of claiming an already-claimed subdomain.
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 concise sentences, front-loading the core action and example. Every word earns its place, with 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 moderate complexity (3 params, no output schema), the description covers purpose, cost, and auth. However, it lacks post-condition details (e.g., DNS propagation) and error handling context, leaving gaps.
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 each parameter. The description adds the example subdomain format and cost/auth note, but does not clarify the optional project_id role or provide further semantics 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 action ('Claim a custom subdomain') and the resource ('point it at an existing deployment'), with an example ('myapp.run402.com'). It distinguishes from sibling tools like add_custom_domain by emphasizing 'custom subdomain'.
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 mentions 'Free, requires service_key auth' but provides no guidance on when to use this tool versus alternatives (e.g., add_custom_domain, delete_subdomain). No explicit when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a smart-contract write call from a KMS signer. The gateway encodes via viem, signs the digest via AWS KMS, and broadcasts. Idempotent on optional idempotency_key. Cost: chain gas at-cost + $0.000005 KMS sign fee per call.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes | Function arguments (must match ABI) | |
| chain | Yes | EVM chain | |
| value | No | Optional native-token value in wei (decimal string) | |
| signer_id | Yes | The KMS signer ID | |
| project_id | Yes | The project ID | |
| abi_fragment | Yes | ABI fragment containing the function definition | |
| function_name | Yes | Function name to invoke | |
| idempotency_key | No | Optional idempotency key — same key returns same call_id without re-broadcasting | |
| contract_address | Yes | 0x-prefixed contract address |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: writing, encoding via viem, signing via AWS KMS, broadcasting, idempotency, and cost. With no annotations, it carries the full burden. However, it does not describe failure modes, return value (likely a call_id), or prerequisites for successful execution.
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, no redundant information, front-loaded with action and resource. Every sentence contributes purpose, process, or cost.
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 high parameter count and complexity (KMS signing, gas costs, idempotency), the description is minimal. It omits return value (call_id?), error handling, prerequisites (signer existence, gas balance), and input format for idempotency_key. An output schema or richer description would be needed for full completeness.
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% description coverage, so baseline is 3. The description adds value by explaining idempotency_key behavior and cost, but does not further clarify complex parameters like args or abi_fragment 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?
Description clearly states the action ('Submit a smart-contract write call'), the source ('from a KMS signer'), and differentiates from sibling tools like contract_read (read) and contract_deploy (deploy new contract) by specifying it's a write call on an existing contract.
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?
Mentions idempotency via idempotency_key and cost structure, which guides when to use and cost implications. Lacks explicit comparison to sibling tools like contract_read vs. contract_deploy, and does not state prerequisites (e.g., signer must be provisioned, chain gas needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploy a smart contract from a KMS signer (signs a contract-creation tx with to: null + data: bytecode). The bytecode is full creation calldata — creation bytecode + ABI-encoded constructor args, concatenated client-side (run402 does NOT compile Solidity). Returns the deterministic CREATE address synchronously in contract_address — known before confirmation, no polling needed to know where the contract lives. Same pricing as contract_call: chain gas at-cost + $0.000005 KMS sign fee.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | Yes | EVM chain (must match the signer's chain) | |
| value | No | Optional native-token value in wei to attach to the deploy (decimal string) | |
| bytecode | Yes | Full creation calldata as 0x-prefixed hex (creation bytecode + ABI-encoded constructor args, concatenated client-side). Non-empty, even-length, ≤ 128 KB. run402 does NOT compile Solidity. | |
| signer_id | Yes | The KMS signer ID (cwlt_...) that will sign + own the new contract | |
| project_id | Yes | The project ID | |
| idempotency_key | No | Optional idempotency key — same key + same bytecode returns same call_id without re-broadcasting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses key behaviors: synchronous return of contract_address before confirmation (no polling needed), pricing details, and that bytecode must be pre-compiled. Missing are authorization requirements (e.g., KMS signer existence) and failure behavior, but overall it provides adequate transparency for most use cases.
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 well-structured. It front-loads the primary action and progressively adds details. Every sentence serves a purpose: action+mechanism, bytecode specification, and return behavior+pricing. No redundancy or 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 no output schema, the description adequately explains the return value (contract_address). It also mentions pricing and deterministic address. However, it could be more complete by mentioning error conditions, confirmation status, or required permissions. For a deployment tool, it covers essential aspects but lacks some edge-case 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 the description adds significant value beyond schema fields. For 'bytecode', it explains it is full creation calldata including constructor args, must be 0x-prefixed hex, and size limit. It clarifies 'value' is optional native token in wei, and 'idempotency_key' behavior. This helps the agent understand parameter semantics deeply.
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 function: 'Deploy a smart contract from a KMS signer'. It details the mechanism (signs a contract-creation tx) and specifies that it returns the deterministic CREATE address. It also distinguishes itself by noting it does NOT compile Solidity and has same pricing as contract_call.
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 explains when to use the tool (to deploy a smart contract) and provides context for bytecode preparation (client-side concatenation, run402 does not compile). It mentions same pricing as contract_call, implicitly guiding against using contract_call for deployment. However, it lacks explicit when-not-to-use guidance or alternative tools beyond the pricing reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only smart-contract call (view/pure functions). No signing, no gas, no billing — pure RPC convenience.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes | Function arguments | |
| chain | Yes | EVM chain | |
| abi_fragment | Yes | ABI fragment containing the view/pure function | |
| function_name | Yes | Function name | |
| contract_address | Yes | 0x-prefixed contract address |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states the tool is read-only, requires no signing/gas/billing, and is a 'pure RPC convenience'. Missing details on failure modes or behavior if a non-view/pure function is provided, but overall adequate.
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 that front-load the key purpose ('Read-only smart-contract call') and pack essential behavioral traits. 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?
The description does not mention what the call returns. For a read-only tool, understanding the output format is important. While the schema coverage is high, the lack of output schema information leaves a gap for agents to infer the response structure.
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 100% description coverage for all 5 parameters, so the bar is low. The description adds no additional parameter-specific details beyond noting the function is view/pure, which is already implied by the tool's purpose. 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 is for read-only smart-contract calls (view/pure functions), explicitly distinguishing it from write operations. The sibling tools include 'contract_call' and 'contract_deploy', which are for write or deploy actions, making the purpose 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?
The description indicates when to use this tool: for read-only calls with no signing, gas, or billing. It implies that for other operations, sibling tools should be used, though it does not explicitly state alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a project auth user with the service key. Can set project_admin and optionally send a trusted invite.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address of the auth user to create or update | ||
| is_admin | No | Set project_admin status for this user | |
| project_id | Yes | The project ID | |
| send_invite | No | Send a trusted invite magic link after creating/updating the user | |
| client_state | No | Optional opaque state preserved through trusted invite verification | |
| redirect_url | No | Required when send_invite=true. Must be an allowed project auth redirect origin. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully convey behavioral traits. It discloses that the tool can create/update and optionally send an invite, but does not describe authorization details beyond 'service key', potential destructive effects (e.g., overwriting existing users), or side effects of the invite. Rate limits and idempotency are also not addressed.
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 of 16 words, which is concise and front-loaded with the main action. However, it could be slightly more structured (e.g., separating create/update and invite functionalities) without adding 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?
With 6 parameters and no output schema, the description covers the core actions but misses critical details: the dependency of 'redirect_url' on 'send_invite' (though present in schema), the nature of 'client_state', and the distinction between creating and updating. The sibling overlap also reduces completeness.
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 summarizes the tool's capabilities but does not add meaning for individual parameters like 'client_state' or 'redirect_url'. It reiterates 'send_invite' and 'is_admin' but without additional context 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?
Description states 'Create or update a project auth user', clearly indicating the verb and resource. However, it does not differentiate from the sibling tool 'invite_auth_user', which likely overlaps in functionality (sending invites). This lack of distinction prevents a perfect score.
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 like 'invite_auth_user'. The description mentions 'with the service key' but does not explicitly state prerequisites or context for choosing this tool over others. No exclusions or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Stripe checkout URL for an organization. Products: balance_topup, tier, email_pack.
| Name | Required | Description | Default |
|---|---|---|---|
| tier | No | Required for product=tier | |
| org_id | Yes | Organization ID to bill | |
| product | Yes | Checkout product | |
| cancel_url | No | Optional checkout cancel redirect URL | |
| success_url | No | Optional checkout success redirect URL | |
| amount_usd_micros | No | Required for product=balance_topup; amount in micro-USD (e.g. 5000000 = $5.00) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies initiating a payment flow but does not disclose side effects, authorization requirements, URL expiration, or idempotency. With no annotations, the description carries full burden but fails to provide necessary 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 very concise (two sentences) and front-loaded with purpose. However, it could include slightly more structure without becoming lengthy.
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 incomplete given the tool's complexity: 6 parameters, no output schema, no annotations. It omits what the tool returns, prerequisites, and error handling, leaving significant gaps 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 description coverage is 100%, so baseline is 3. The description adds minimal value by listing product names, but the schema already documents each parameter's meaning and constraints.
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 Stripe checkout URL for an organization and lists three products. However, it does not differentiate from sibling billing tools like billing_history or get_quote.
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 is provided on when to use this tool versus alternatives. It does not explain prerequisites, when to call this tool, or what not to use it for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an email-based organization (Stripe-only, no wallet required). Sends a verification email. Idempotent — duplicate emails return the existing organization.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address to create an organization for (Stripe-only, no wallet) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses idempotency and email sending. With no annotations, the description carries full burden. It doesn't mention failure modes (invalid email, Stripe issues) or confirm that creation is non-destructive. Adequate but not thorough.
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 sentences: first states purpose and constraints, second adds behavioral traits. No redundant words, front-loads key info.
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, idempotency, email verification. Lacks response format, error handling, and whether operation is synchronous. Adequate for a simple creation tool but missing typical context.
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?
Only one parameter 'email' with schema description already covering constraints. The tool description restates 'Stripe-only, no wallet' but does not add new parameter-related meaning beyond the schema. With 100% schema coverage, baseline is 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?
Clearly states the verb 'Create' and resource 'email-based organization'. Adds constraints 'Stripe-only, no wallet required', which helps distinguish from wallet-based org creation. However, it does not explicitly differentiate from sibling tool 'create_org', which may be more general.
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 context that it sends a verification email and is idempotent. Implies usage for email-based, Stripe-only organizations, but no explicit guidance on when to use this versus alternatives like 'create_org' or 'link_wallet_to_organization'. No when-not-to-use statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a durable function run with a required idempotency key. Supports immediate, delayed, or run_at scheduling, expiry, retry policy, and optional wait. Use this instead of ad hoc cron/polling when work must survive retries or be redriven.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Function name to run | |
| wait | No | Wait until the run becomes terminal before returning. | |
| delay | No | Delay before first attempt, such as `10m`, `1h`, or `3d`. Mutually exclusive with run_at. | |
| retry | No | ||
| run_at | No | Absolute ISO-8601 first-attempt time. Mutually exclusive with delay/delay_seconds. | |
| payload | No | JSON object payload delivered to the handler | |
| event_type | Yes | Application event type delivered to the function run handler | |
| expires_at | No | Absolute ISO-8601 expiry time. | |
| project_id | Yes | The project ID | |
| timeout_ms | No | Maximum wait time in milliseconds. | |
| delay_seconds | No | Delay before first attempt in seconds. Mutually exclusive with delay and run_at. | |
| expires_after | No | Relative expiry duration, such as `1d`. | |
| idempotency_key | Yes | Required idempotency key. Reuse it when retrying the same logical work item. | |
| poll_interval_ms | No | Polling interval in milliseconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions idempotency key, scheduling options, expiry, retry policy, and optional wait, but lacks details on conflict handling (e.g., reusing idempotency key) and whether the call is synchronous or asynchronous. This is adequate but not fully transparent.
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 focused sentences: the first states the core action and requirement (idempotency key), the second lists capabilities and usage context. No wasted words; essential information 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 the tool's complexity (14 parameters, nested retry object) and lack of output schema, the description covers the main behavioral aspects (idempotency, scheduling, expiry, retry, wait). It omits payload and event_type details, but these are in the schema. Overall, it is sufficiently complete 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 high (93%), so the baseline is 3. The description adds context by grouping scheduling types (immediate, delayed, run_at) and mentioning retry policy, but does not significantly elaborate on individual parameters beyond what the schema already provides.
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 durable function run, specifies the required idempotency key, and lists key features like scheduling, expiry, and retry policy. It distinguishes itself from siblings by contrasting with ad hoc cron/polling, making its 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 explicitly states 'Use this instead of ad hoc cron/polling when work must survive retries or be redriven,' providing clear guidance on when to choose this tool over alternatives. It also implies its suitability for durable, retryable work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a project-scoped mailbox local part. The managed address is @.mail.run402.com; matching slugs in other projects are allowed. Returns mailbox_settings and next_actions when the gateway provides default-role repair guidance. Not idempotent: same-project slug conflicts/cooldowns/limit errors are surfaced.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Project-scoped mailbox local part (3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens). Creates <slug>@<project-mail-host>.mail.run402.com | |
| project_id | Yes | The project ID to create a mailbox for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: it states non-idempotency, surfaces conflict/cooldown/limit errors, and mentions conditional return of mailbox_settings and next_actions. This provides good transparency beyond creation.
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 four short sentences, each adding distinct value: creation action, address format, conditional return, and non-idempotency warning. No redundancy or 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?
The description covers creation, constraints, and error conditions but lacks detail on return structure beyond the conditional scenario. It does not explain what mailbox_settings or next_actions contain, leaving some ambiguity for the agent. Overall adequate but not exhaustive.
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 covers both parameters with descriptions, so baseline is 3. The description adds the specific address format (<slug>@<project-mail-host>.mail.run402.com) and clarifies cross-project allowance, which goes beyond the schema's parameter 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 the tool creates a project-scoped mailbox local part, specifies the resulting address format, and distinguishes from sibling tools like 'update_mailbox' or 'delete_mailbox' by emphasizing creation and cross-project slug allowance.
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 does not explicitly state when to use this tool versus alternatives. It only implies creation usage and mentions error conditions, but lacks guidance on when not to use it or how it differs from other mailbox-related tools like 'set_mailbox_defaults'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Telegram routing rule: one match (project_id / source / event_types / classes, all ANDed, each optional — omitted = wildcard) routes to one Telegram binding. Requires operator_passkey assurance. An unusable or foreign telegram_binding_id returns the same 404 as a nonexistent one.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Only match events from this source: 'app' (a deployed function's events.emit(...) calls) or 'platform' (deploys, lifecycle, verification, ...). Omit to match both. | |
| classes | No | Only match these notification classes (matches ANY listed value), e.g. 'lifecycle', 'app'. Omit to match any class. An empty array matches NOTHING (not a wildcard). | |
| project_id | No | Only match events for this project. Omit to match every project (wildcard). | |
| event_types | No | Only match these exact event_type names (matches ANY listed value). Omit to match any event_type. An empty array matches NOTHING (not a wildcard). | |
| telegram_binding_id | Yes | The Telegram binding (chat) this rule routes matching events to. Must be an active binding owned by this operator — see list_notification_channels. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description compensates by detailing critical behavioral aspects: empty arrays match nothing, omitted fields act as wildcards, and invalid binding IDs return 404. It could mention the return value or side effects, but the provided details are sufficient.
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 sentences, front-loaded with the core action, and a second sentence adding critical behavioral notes. No unnecessary words or 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 and lack of output schema, the description covers the input behavior well, including edge cases and prerequisites. It does not specify the return value (e.g., created rule ID), but the focus is on input, which is adequately explained.
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 schema covers all 5 parameters, but the description adds significant meaning: it explains the AND logic for match fields, clarifies wildcard behavior for omitted fields, and notes that empty arrays are not wildcards. This goes beyond the 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 the tool's purpose: 'Create a Telegram routing rule' with specific matching and routing logic. It distinguishes from sibling tools like list_notification_rules and delete_notification_rule by detailing the creation aspect.
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 mentions the requirement 'Requires operator_passkey assurance' and explains the 404 behavior for invalid bindings, providing context for correct usage. However, it does not explicitly state when to use this tool over alternatives like test_notification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an empty organization on the prototype tier (POST /orgs/v1); you become its owner. Accepts only an optional display_name (no tier input); the response reports tier, lease_started_at, and lease_expires_at. Step-up gated; the soft per-owner free-org cap may return FREE_ORG_OWNER_LIMIT_EXCEEDED.
| Name | Required | Description | Default |
|---|---|---|---|
| display_name | No | Optional free-text label (e.g. `Kychee`). Non-unique, not an id. Omit for an unlabeled org. There is no tier input at create; the response reports the created org's prototype tier/lease state. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses ownership, tier limitation, response fields (tier, lease times), step-up gating, and potential error code. With no annotations, this fully covers behavioral traits.
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, no wasted words, front-loaded with the main action, followed by important constraints and response details.
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 simple tool with one parameter, the description covers creation, inputs, outputs, and a possible error. Could mention that step-up gating is a prerequisite, but overall adequate.
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 has 100% coverage with a good description. The tool description adds extra context (non-unique, not an id, no tier input), enhancing understanding 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?
Clearly states it creates an empty organization on the prototype tier, with the user becoming owner. Specifies the endpoint and uniquely identifies the action among many sibling 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?
Provides context that it creates on prototype tier, accepts optional display name, and mentions a possible error cap. Doesn't explicitly contrast with alternatives, but is sufficient for the single creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a contained branch project from a fresh or existing snapshot. Email is sandboxed/off and cron is off unless explicitly enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Human-readable branch project name. | |
| ttl_days | No | Branch TTL in days. Default 7, max 30. | |
| email_mode | No | Branch email containment. Default sandbox. | |
| project_id | Yes | Parent project ID. | |
| enable_cron | No | Enable scheduled functions on the branch. Default false. | |
| from_snapshot_id | No | Existing ready snapshot to branch from. Omit to capture a fresh contained snapshot first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses key defaults (email sandboxed/off, cron off) but omits other traits like permissions needed, reversibility, or side effects of branching from raw snapshot.
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 sentences front-load purpose and key behaviors without redundancy or 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?
Covers main purpose and defaults but misses details like return value (project ID?), ttl_days default (7), and what 'contained' entails. Adequate for a 6-param tool with full schema coverage.
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 6 parameters with descriptions. Description adds context by summarizing defaults (email_mode and enable_cron) and the choice between fresh or existing snapshot (from_snapshot_id), enhancing schema meaning.
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 ('Create a contained branch project') and resource ('branch project'), distinguishing it from sibling tools like create_project_snapshot and list_project_branches.
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 when to use (creating a branch) but lacks explicit guidance on when not to use or alternatives among many sibling tools (e.g., renew_project_branch, delete_project_branch).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Issue a per-project capability grant to a wallet (for agent/CI principals that aren't broad org members). Params: project_id, wallet, capability (e.g. deploy, functions:write), optional policy / expires_at. Requires you to be an owner of the project's org.
| Name | Required | Description | Default |
|---|---|---|---|
| policy | No | Optional capability-scoping policy object (gateway-interpreted). | |
| wallet | Yes | EVM address (or named wallet) the grant is issued to. | |
| capability | Yes | Capability to grant, e.g. `deploy` or `functions:write`. | |
| expires_at | No | Optional ISO-8601 expiry. Omit for a non-expiring grant. | |
| project_id | Yes | Project id to grant access to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses ownership requirement and action type, but does not detail idempotency, side effects, or behavior on duplication. It is adequate but not exhaustive.
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 concise paragraph, front-loaded with the main action, and every sentence adds value. No unnecessary 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 (5 params, nested object), the description covers purpose, parameters, and access control. It lacks details on return values or error conditions, but is generally complete for a creation 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 lists parameters with examples, but adds little beyond the schema descriptions beyond summarizing and providing an example for capability.
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 issues a per-project capability grant to a wallet, targeting agent/CI principals that aren't broad org members. It uses a specific verb (Issue) and resource (grant), and distinguishes from the sibling revoke_project_grant tool.
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 specifies it is for agent/CI principals not in broad org membership and requires ownership of the project's org. However, it does not explicitly mention alternatives or 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.
Capture a manual project data snapshot. Snapshots are internal restore points, not downloadable archives.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID to snapshot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It states snapshots are internal restore points and not downloadable, but omits details about permissions, rate limits, side effects, or what happens when creating many snapshots. This is minimal behavioral information.
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, no wasted words. Direct and front-loaded with the key action and clarification.
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 (1 param, no output schema), the description covers the purpose and nature of snapshots. However, it lacks any hint about return values or confirmation, which would be useful since no output schema exists.
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 schema has 100% coverage for the single parameter (project_id), so baseline is 3. The description adds no extra meaning beyond the schema; it does not explain the format or constraints of project_id.
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 'Capture' and the resource 'manual project data snapshot'. It also distinguishes snapshots from downloadable archives, but does not explicitly differentiate from sibling tools like delete_project_snapshot or restore_project_snapshot.
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. The description does not specify prerequisites, contexts, or exclusions. For example, it doesn't mention that snapshots can be restored or listed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a deployed function from a project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Function name to delete | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks details on irreversibility, dependencies, or confirmation steps. 'Delete' implies a destructive action but does not confirm whether the operation is permanent or if it 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?
Single sentence with 7 words, front-loaded with the verb and resource. No extraneous 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?
For a simple delete operation, the description is minimally adequate but lacks context on return values, error conditions, and side effects. Without annotations, more completeness would be beneficial.
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%, and the description adds no extra meaning beyond the already clear parameter names and types. 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 action ('Delete') and the resource ('a deployed function from a project'), distinguishing it from sibling tools like delete_mailbox or delete_project.
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 vs alternatives (e.g., deactivate vs delete), no prerequisites or conditions mentioned. Among many function-related tools, the description does not help an agent decide when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete the project's mailbox (irreversible — drops all messages and webhook subscriptions). Requires confirm=true. If mailbox_id is omitted, resolves the project's mailbox.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true. Destructive: deleting a mailbox drops all messages and webhook subscriptions and is irreversible. | |
| mailbox_id | No | Mailbox to delete — slug or id (mbx_...). If omitted, deletes the project's only mailbox; on a project with more than one mailbox, omitting it returns an ambiguity error naming the slugs. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the irreversible nature ('drops all messages and webhook subscriptions') and the need for confirm=true, which is critical for a destructive action. No annotations present, so description carries full burden and meets it well.
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 with no filler. Front-loaded with purpose and warnings. Every sentence earns its place.
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 3 parameters, no output schema, and no annotations, the description covers all necessary behavioral and parameter details, including error cases and prerequisites, making it complete for correct invocation.
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?
Despite 100% schema coverage, the description adds significant extra semantics: resolution behavior for omitted mailbox_id, ambiguity error details, and the implication of project scope. This goes beyond the schema's 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 'Delete the project's mailbox' with specific verb and resource. It distinguishes from siblings like create_mailbox and update_mailbox by specifying the irreversible deletion of all messages and webhook subscriptions.
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 requires confirm=true and explains behavior when mailbox_id is omitted, including the ambiguity error for multi-mailbox projects. However, no direct comparison to alternatives or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a webhook. Idempotent — succeeds even if already deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID | |
| webhook_id | Yes | The webhook ID (whk_...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It discloses idempotency, key behavior. It does not mention other traits like potential impact on deliveries, but for a simple delete, this is adequate.
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 with no filler. Front-loaded with the action. 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?
The description is minimal but covers the core purpose. Lacks information about return values or side effects, which given no output schema could be helpful. Adequate for a simple 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 all parameters described. The description adds no extra meaning beyond the schema, so 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 'Delete a webhook', which is a specific verb-resource pair. It also notes idempotency, distinguishing it from other webhook operations like register, update, or list.
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?
Usage is implied by the name and description, but there is no explicit guidance on when to use vs alternatives, nor when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a Telegram routing rule. Requires operator_passkey assurance.
| Name | Required | Description | Default |
|---|---|---|---|
| rule_id | Yes | The routing rule id to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only mentions authentication requirement, missing details on idempotency, error handling, side effects, and irreversibility.
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?
Extremely concise at 8 words, no fluff, but could include more information while remaining succinct.
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 low complexity but description omits critical context such as whether deletion is irreversible, error behavior, and what 'operator_passkey assurance' entails.
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% (rule_id described in schema). Description adds no additional meaning beyond schema, so baseline score of 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 clearly states the action 'Delete a Telegram routing rule', specifying the resource and action. It distinguishes from sibling tools like 'create_notification_rule' and 'list_notification_rules'.
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?
Description provides a prerequisite ('Requires operator_passkey assurance') but lacks explicit guidance on when to use this tool versus alternatives, nor 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.
Delete one authenticated-user passkey by id.
| Name | Required | Description | Default |
|---|---|---|---|
| passkey_id | Yes | Passkey ID to delete | |
| project_id | Yes | The project ID | |
| access_token | Yes | Authenticated user's access_token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Delete' but does not disclose whether the action is irreversible, what happens to related data, or if authentication is required (though access_token is in schema). Minimal 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?
Single sentence, front-loaded with verb and resource. No unnecessary words or repetition.
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 simple deletion tool with 3 parameters and no output schema, the description is adequate but lacks details on return values, error cases, or side effects. It is minimally 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% and schema descriptions are adequate. The description does not add additional meaning beyond 'by id' for the passkey_id parameter. Baseline 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 the action ('Delete') and the resource ('one authenticated-user passkey by id'). It distinguishes from sibling tools like list_passkeys and create_auth_user.
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 when to use (delete a passkey by id) but does not provide explicit guidance on when not to use it, prerequisites, or alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Immediately and irreversibly delete a project: the gateway runs the full destructive cascade (drop tenant schema, delete Lambda functions, release subdomains, tombstone mailbox, remove sender domain, wipe secrets and app versions) and sets status=purged. This tool also removes the project from the local key store. Distinct from the automatic lease-expiry grace window — this action is the explicit purge and cannot be undone. To recover from a missed renewal use set_tier instead.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID to delete (irreversible cascade purge) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It details the full destructive cascade (drop schema, delete functions, release subdomains, tombstone mailbox, remove sender domain, wipe secrets and app versions, set status=purged, remove from local key store) and explicitly states the action is irreversible. This provides comprehensive behavioral 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 a single paragraph that front-loads the key action and details. While it is informative, it is somewhat verbose (over 50 words) and could be more concise without losing essential information. It earns a 4 for being well-structured but slightly wordy.
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 one parameter, no output schema, and no annotations, the description is remarkably complete. It explains the effects thoroughly, distinguishes from related actions, and provides all necessary context for an AI agent to invoke it 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?
The single parameter `project_id` has a schema description already stating it's the project ID for irreversible deletion. The tool description reiterates this but does not add additional semantic information beyond what the input schema provides. With 100% schema coverage, the description adds minimal extra value for parameter understanding.
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 'Immediately and irreversibly delete a project' and enumerates specific destructive operations (drop tenant schema, delete Lambda functions, etc.). It distinguishes itself from the automatic lease-expiry grace window and mentions the alternative tool `set_tier`, making its purpose unambiguous and distinct from sibling 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 states when to use this tool (explicit purge) and when not to (to recover from a missed renewal, use `set_tier`). It also clarifies that this action is distinct from the lease-expiry grace window, providing clear usage context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a contained branch project and purge its resources.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Parent project ID. | |
| branch_project_id | Yes | Branch project ID to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states delete and purge, implying destructiveness. Missing details on permanence, cascading effects, or required 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?
Single, clear sentence without fluff. Efficient but could be slightly more informative without breaking conciseness.
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?
Simple tool but destructive; lacking return value description, error scenarios, and prerequisites. Incomplete for safe agent invocation.
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 already describes both parameters fully (100% coverage). Description adds no additional parameter 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?
The description clearly states the verb 'Delete' and the resource 'contained branch project', with additional action 'purge its resources'. It distinguishes from sibling tools like 'create_project_branch' and 'renew_project_branch'.
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. Does not mention prerequisites, when not to use, or any context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a project data snapshot and release its CAS references.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID that owns the snapshot. | |
| snapshot_id | Yes | Snapshot ID to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions releasing CAS references, but without annotations, it fails to disclose key behavioral traits such as permanence of deletion, required permissions, whether it can be undone, or any 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 a single concise sentence that efficiently conveys the main action. It could be slightly expanded, but it is not verbose.
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 a simple delete operation with only two parameters, the description is mostly adequate, but it lacks behavioral and usage context that would help an agent decide when and how to invoke it safely.
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 coverage, the input schema already describes the parameters clearly. The description adds no additional meaning beyond the schema, so baseline 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 the action ('Delete') and the resource ('project data snapshot') and adds detail about releasing CAS references, which distinguishes it from related tools like create, get, or restore.
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 such as restore_project_snapshot or other deletion tools. No prerequisites or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a secret from a project.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Secret key to delete | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the action. It does not mention that deletion is permanent, that it requires appropriate permissions, or any 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 a single sentence with no wasted words, achieving maximum conciseness.
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 too minimal for a destructive tool with no annotations or output schema. It lacks context about irreversibility, permissions, and post-deletion state.
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 the description adds no extra meaning beyond the schema's parameter descriptions. The 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 the verb 'delete' and the resource 'secret' in the context of a project, distinguishing it from related tools like set_secret and list_secrets.
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 is provided on when to use this tool versus alternatives, nor are there prerequisites or caveats mentioned. The description is purely functional.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule the KMS key for a signer for deletion (7-day AWS minimum window). Refused if the signer has on-chain balance ≥ dust — drain first.
| Name | Required | Description | Default |
|---|---|---|---|
| signer_id | Yes | The KMS signer ID. Schedules KMS key deletion (7-day window). Refused if balance >= dust — drain first. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses the 7-day minimum window for AWS KMS deletion, the balance condition, and the refusal behavior. However, it does not mention permissions required, whether deletion can be reversed within the window, or the return value.
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 is front-loaded with the core action and includes key constraints. No unnecessary 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?
For a destructive tool with no output schema, the description covers the main behavioral aspects: action, time window, and precondition. It could be improved by mentioning whether the deletion happens automatically after 7 days, but it is sufficiently complete for an AI 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 description coverage is 100%. The signer_id description in the schema repeats the tool description, adding little new value. The description does not provide additional per-parameter details beyond what is 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 that the tool schedules the KMS key for a signer for deletion with a 7-day window, and mentions a precondition about balance. It matches the name 'delete_signer' and distinguishes from sibling 'drain_signer'.
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 'Refused if the signer has on-chain balance ≥ dust — drain first', which guides the agent to use the sibling 'drain_signer' tool before this one. It provides clear context for when to use and when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Release a custom subdomain. The URL will stop serving content.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Subdomain name to release (e.g. 'myapp') | |
| project_id | No | Optional project ID for ownership verification. Uses stored service_key for auth. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states that the URL stops serving content, which is a key effect. However, it does not mention whether the subdomain becomes available for reuse, if there are any irreversible consequences, or authorization requirements (e.g., ownership).
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 sentences with no wasted words. The second sentence adds value by stating the effect. Could be slightly more structured (e.g., indicating return value) but is appropriately concise.
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 simple deletion tool with no output schema, the description covers purpose and effect. However, it lacks details on return behavior, error conditions, and prerequisites. Given the absence of annotations, more completeness would be beneficial.
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 descriptions in the schema (100% coverage). The tool description does not add any extra meaning beyond what the schema provides, so it meets the baseline but does not improve understanding.
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 'Release a custom subdomain' clearly states the action and resource. The added detail 'The URL will stop serving content' clarifies the consequence. It distinguishes from siblings like 'claim_subdomain' and 'add_custom_domain', but does not explicitly differentiate from 'remove_custom_domain' (which may have similar semantics).
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 vs alternatives such as 'remove_custom_domain' or 'disable_sender_domain_inbound'. The description does not mention prerequisites, side effects, or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a published app version.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID | |
| version_id | Yes | The version ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral traits. It only states 'Delete a published app version' without disclosing side effects, irreversibility, or prerequisites, which is insufficient for a destructive operation.
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 single-sentence description is concise and front-loaded with the action. However, it is perhaps too brief, lacking additional context that could improve usability without adding significant 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 the lack of output schema and the destructive nature of the tool, the description does not explain what happens after deletion (e.g., permanent removal, effect on app status). It leaves critical behavioral details unspecified.
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% (both parameters have descriptions). The description adds no extra meaning beyond what the schema already provides, meeting the baseline but not exceeding it.
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 the specific resource 'published app version', distinguishing it from siblings like publish_app, update_version, and list_versions.
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 is provided on when to use this tool versus alternatives, such as update_version or unpublish flows. The description merely states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Demote a user from project_admin role by email. Reverts to default authenticated role. Requires service_key.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address of the user to demote from project_admin | ||
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It states the role change and a requirement, but does not mention side effects, idempotency, reversibility, or error states. Adequate but not comprehensive.
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 covering action, target, effect, and requirement. Very concise and front-loaded. Could be improved by splitting into two sentences for readability, but 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?
For a simple mutation tool with no output schema, the description covers the essential: what it does, the new role, and a key requirement. Missing post-conditions or relationship to promote_user, but still sufficient.
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 no extra meaning beyond the schema descriptions (email and project_id are already described). No format, constraints, or examples provided.
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 ('Demote a user from project_admin role by email'), specifies the resource (user by email), and the outcome ('Reverts to default authenticated role'). It distinguishes from sibling tools like promote_user. This is specific and actionable.
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 mentions a prerequisite ('Requires service_key') but does not provide explicit guidance on when to use this tool versus alternatives like promote_user or remove_org_member. It lacks when-not-to-use context or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified apply primitive. Accepts a structured ReleaseSpec — database (migrations + expose), value-free secrets.require/delete declarations, functions, site, site.public_paths, subdomains, and routes.replace web routes — with explicit replace vs patch semantics per resource. Migration entries use id for immutable versioned SQL or name for generated/idempotent content-tracked SQL; name compiles client-side to _<sha256(sql)[0:16]>. Use site.public_paths for clean static URLs such as /events backed by release asset events.html; explicit mode does not expose /events.html unless separately declared, while mode: 'implicit' restores filename-derived reachability and can widen access. Route entries map exact/final-wildcard browser paths like /admin and /admin/* to Node 22 Fetch Request -> Response functions, or exact GET/HEAD method-aware static aliases such as /events to { type: 'static', file: 'events.html' }; intentional read-only GET/HEAD wildcard function routes may set acknowledge_readonly: true. Direct /functions/v1/:name remains API-key protected. Secret values must be set first with set_secret, never placed in deploy specs. All bytes ride through CAS (no inline-body cap). Returns release_id, URLs, warnings, and a structured progress-event log. Stops before upload/commit on confirmation-required warnings unless reviewed codes are passed with allow_warning_codes or allow_warnings is true.
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Diff base. Default `{ release: 'current' }`. Use `{ release: 'empty' }` for a fresh deploy that fails if a release already exists. | |
| i18n | No | Routed-locale-context release slice. Omit to carry forward from base release; pass null to clear the slice; pass { defaultLocale, locales, detect? } to replace. Drives the negotiated locale that the gateway surfaces to routed HTTP function invocations via x-run402-locale and x-run402-default-locale request headers (omitted entirely when the active release has no i18n slice). Static-route hits do NOT receive locale negotiation. | |
| site | No | ||
| assets | No | v1.48 unified-apply assets slice. Asset writes promote inside the same activation transaction as functions/site/secrets so a release flips atomically. | |
| routes | No | Apply-v1 web routes. Omit or pass null to carry forward base routes; pass { replace: [] } to clear routes; pass { replace: [{ pattern, methods?, target: { type: 'function', name } }] } for functions or exact GET/HEAD { target: { type: 'static', file } } entries for method-aware static route aliases. Prefer site.public_paths for ordinary clean static URLs. | |
| secrets | No | ||
| database | No | ||
| functions | No | ||
| project_id | Yes | Project ID to deploy to (from provision). | |
| subdomains | No | At most one subdomain per project — multi-element `set` is rejected with SUBDOMAIN_MULTI_NOT_SUPPORTED. | |
| allow_warnings | No | Continue past plan warnings that require confirmation. Default false: the tool stops before upload/commit so an agent can set missing secrets or inspect warnings. | |
| idempotency_key | No | Optional client idempotency key. Combined with the project id and gateway-computed manifest digest to deduplicate retries. | |
| allow_warning_codes | No | Continue past specific reviewed plan warning codes. Prefer this to allow_warnings when only one known warning class is intentional. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It extensively covers behavioral details: CAS transfer, idempotency with idempotency_key, warning handling (allow_warnings, stop before upload), return values (release_id, URLs, warnings, logs), and secret management (must be set separately). This is highly transparent for a complex tool.
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 verbose and reads like a specification. While it is front-loaded with 'Unified apply primitive', it includes many detailed clauses that could be streamlined for faster parsing. Some sentences are dense and could be broken down.
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 (13 parameters, nested objects), the description covers most aspects: migrations, routing, secrets, assets, site, subdomains, and return values. There is no output schema, but the description lists return values. No major gaps are apparent.
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 69%, and the description adds significant meaning beyond the schema. It explains concepts like migration id vs name semantics, public_paths modes (explicit/implicit), route target types (function/static), and the secrets require/delete pattern. This adds value for an agent understanding parameter usage.
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 is a 'Unified apply primitive' and lists the components it handles (database, secrets, functions, etc.). However, it does not explicitly distinguish itself from sibling tools like deploy_function or deploy_site, which would help an agent choose correctly.
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 detailed semantics (e.g., replace vs patch, public_paths modes) but lacks explicit guidance on when to use this tool vs alternatives like deploy_function or deploy_site. The context implies it's for complex multi-resource deployments, but no direct comparison is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only authenticated diagnostics for a Run402 public URL or host/path pair. Explains whether the current live release would serve the URL, including match, diagnostic body status, static manifest/cache metadata when returned, structured warnings for ignored query/fragment, and next steps. This does not fetch bytes, purge cache, mutate deploy state, or expose internal CAS URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Absolute HTTP(S) public URL to diagnose. Mutually exclusive with host/path. | |
| host | No | Lower-level hostname form without scheme, path, query, or fragment. | |
| path | No | Lower-level public URL path. Must start with '/' when supplied. | |
| method | No | HTTP method to diagnose. Defaults to gateway behavior when omitted. | |
| project_id | Yes | Project ID used for local apikey lookup. It is not sent as a query parameter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It explicitly states the tool is read-only, does not fetch bytes, purge cache, mutate deploy state, or expose internal CAS URLs. It also lists what the diagnostic includes (match, body status, manifest metadata, structured warnings), providing comprehensive 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 a single, well-structured paragraph of three sentences. It is concise, front-loaded with the core purpose, and every sentence adds value without redundancy. Ideal length for quick comprehension.
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 and multiple parameters, the description thoroughly explains the tool's behavior, expected diagnostic output (match, status, metadata, warnings), and what it does not do. It covers all necessary context for an agent to decide when and how to use it.
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 all 5 parameters. The description adds context that the tool works for URL or host/path pairs and mentions the method, but does not significantly enhance parameter understanding beyond the schema. Baseline of 3 is appropriate as the schema already does the heavy lifting.
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 'Read-only authenticated diagnostics for a Run402 public URL or host/path pair' and enumerates specific diagnostic outputs (match, body status, manifest metadata, warnings). It also distinguishes itself by explicitly listing what it does not do, differentiating it from siblings like 'deploy' or 'diagnose_public_url'.
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 explains the tool's purpose and mentions it provides diagnostics for public URLs or host/path pairs, but does not explicitly state when to avoid this tool in favor of alternatives (e.g., 'diagnose_public_url'). The read-only nature and non-mutating behavior are clear, but exclusion criteria are lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the recorded phase-event stream for a deploy operation. Returns the same DeployEvent shapes the deploy tool emits inline during an in-flight deploy — useful for inspecting a deploy after the fact (e.g., a deploy that the agent didn't observe directly, or one being resumed from a different process).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID that owns the operation. Required (apikey-gated endpoint). | |
| operation_id | Yes | Operation id returned by a prior `deploy` call. Must start with `op_`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist. Description implies it's a read-only fetch but does not disclose auth requirements, error behavior, or rate limits. It is clear it returns event shapes similar to deploy.
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 main action, no redundant information. 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?
No output schema, but description explains return type (DeployEvent shapes). Use cases are covered. Minor omission: no mention of ordering or pagination for the event stream.
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 already documented. The description adds context about operation_id being from a prior deploy call but does not provide new semantics 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?
Description clearly states the verb 'fetch' and resource 'recorded phase-event stream for a deploy operation'. It distinguishes from sibling tools like deploy and deploy_resume by specifying it's for after-the-fact inspection.
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?
Description provides explicit use cases (inspecting a deploy after the fact, for observers or resumption) but does not explicitly state when not to use or compare to alternatives like deploy_list or deploy_release_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploy a serverless function (Node 22) to a project. Handler signature: export default async (req: Request) => Response. The function can import { db, adminDb, auth, email, ai } from '@run402/functions' — auto-bundled by the platform. Additional npm packages are bundled at deploy time when listed in deps (bare names resolve to latest; pinned/range specs are honored verbatim; @run402/functions and run402-functions rejected; max 30 entries; native binaries rejected). For schedule/email background triggers, prefer a unified deploy manifest with functions.replace.<name>.triggers[] so every trigger creates a durable function run. The response includes runtime_version (the bundled @run402/functions version — surface as 'Functions runtime version', never bare 'runtime'), deps_resolved (map of dep name → installed concrete version), and an optional top-level warnings array (sibling to the function record).
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | TypeScript or JavaScript source code. Must export a default async function: export default async (req: Request) => Response | |
| deps | No | Optional npm package specs to install and bundle. Bare names (e.g. 'lodash') resolve to latest at deploy time; pinned (e.g. 'lodash@4.17.21') or range specs ('date-fns@^3.0.0') are honored verbatim. '@run402/functions' (auto-bundled) and 'run402-functions' (legacy name) are rejected. Max 30 entries, max 200 chars per spec. Native binary modules (sharp, canvas, native bcrypt, etc.) are rejected. | |
| name | Yes | Function name (URL-safe slug: lowercase, hyphens, alphanumeric, e.g. 'stripe-webhook') | |
| config | No | Optional function configuration | |
| schedule | No | Cron expression (5-field, e.g. '*/15 * * * *') to run the function on a schedule. Pass null to remove an existing schedule. | |
| project_id | Yes | The project ID to deploy the function to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses handler signature, bundled imports, dependency resolution rules (max entries, rejection of native binaries and @run402/functions), and response fields (runtime_version, deps_resolved, warnings). It does not mention authentication requirements, rate limits, or side effects beyond creation/ update, but the disclosed details are extensive and useful.
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 appropriately sized for the tool's complexity. It is front-loaded with the core purpose and progressively adds detail. Every sentence contributes value, though slightly longer than minimal. No redundancy or 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 6 parameters, no output schema, and no annotations, the description is fairly complete. It covers handler, dependencies, response, and special notes on schedule triggers. It lacks error handling details or failure modes, but the provided information is sufficient for an agent to 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 coverage is 100% (baseline 3). The description adds significant meaning: for 'deps', it explains bundling mechanics, rejection rules, and limits; for 'code', it provides exact handler signature; for 'schedule', it clarifies cron format and removal; for 'config', it notes default values. This goes well beyond the schema's 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 'Deploy a serverless function (Node 22) to a project', specifying the verb (deploy), resource (serverless function), and context (Node 22, project). It distinguishes from siblings like list_functions, delete_function, and the generic deploy tool by focusing on function deployment with explicit handler and runtime details.
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 a guideline for schedule/email triggers ('prefer a unified deploy manifest'), but does not explicitly state when to use this tool versus alternative siblings (e.g., update_function, deploy, deploy_site). It lacks directives on when not to use it or comparison with other tools, leaving the agent without clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent deploy operations for a project. Returns operation_id, status, release_id, and timestamps. Use this to build deploy-history UIs or to find a recent operation_id to feed into deploy_resume / deploy_events. Pass limit to bound the result set; the gateway also returns a cursor for pagination when there are more.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of operations to return. Forwarded to the gateway as `?limit=`; the gateway picks a default when omitted. | |
| cursor | No | Pagination cursor returned by a previous deploy_list response. Forwarded to the gateway as `?cursor=`. | |
| project_id | Yes | Project ID to list operations for. Required (apikey-gated). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It describes the listing behavior and pagination, and implies it's a read-only operation. It could mention that no side effects occur, but the context suffices.
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 purpose and output, second explains usage and parameters. No wasted words, front-loaded with essential info.
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 mentions the return fields and pagination. Parameter behavior is explained. It is sufficiently complete for an agent to use 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%, but the description adds context beyond the schema, explaining that limit bounds results and cursor enables pagination. This helps the agent understand the parameters' roles in the gateway interaction.
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 recent deploy operations for a project, specifying the return fields (operation_id, status, release_id, timestamps). It distinguishes from siblings by suggesting use to feed deploy_resume and deploy_events.
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 use cases (build deploy-history UIs, find operation_id for other tools) and explains how to use limit and cursor. It does not explicitly state when not to use, but the guidance is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a persisted apply plan against a contained branch and return the rehearsal report. Source project and plan stay untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | Persisted apply plan ID returned by deploy planning. | |
| teardown | No | Rehearsal branch cleanup policy. Default keep. | |
| project_id | No | Project ID for operator-approval metadata and follow-up status reads. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that the source project and plan stay untouched, which is a critical non-destructive behavioral guarantee. It also mentions a 'contained branch' and the teardown parameter provides cleanup policy. However, it does not detail permissions, error states, or side effects like branch creation. Since no annotations are provided, the description carries full burden and does so reasonably well.
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 long with no wasted words. The first sentence defines the primary action and the second sentence adds a key behavioral qualifier. It is front-loaded and appropriately sized for the tool's 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 absence of an output schema and annotations, the description is somewhat minimal. It does not explain the rehearsal report content, prerequisites (e.g., how to obtain a plan_id), or alternative tools. However, for a tool that is part of a deployment pipeline, the description covers the essential purpose and key constraint of non-destructiveness.
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 add any additional meaning or context beyond what the parameter descriptions already provide. For example, it does not explain the teardown enum values or the role of project_id in metadata.
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: run a persisted apply plan against a contained branch and return a rehearsal report. It specifies the resource (persisted apply plan) and the outcome (rehearsal report), and the verb 'rehearse' distinguishes it from sibling tools like 'deploy' (actual deployment) or 'deploy_release_*' (release management).
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 no explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for different scenarios. The usage context is only implied by the name 'rehearse' and the description of non-destructive behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the current-live release inventory for a project. Returns release_id: null with an empty current-live inventory when no release is active yet. Use this before deploy diffs to understand what is currently serving. Canonical SDK errors are preserved.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID to inspect. | |
| site_limit | No | Maximum site path entries to include. Gateway default: 5000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that when no release is active, it returns null and empties inventory, and preserves canonical SDK errors. With no annotations, the description carries full burden; it is decent but could explicitly state read-only behavior or 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?
Three efficiently front-loaded sentences with zero waste: purpose, null-case behavior, and usage context with error handling. 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?
Adequately covers purpose, null behavior, use case, and error preservation for a simple 2-parameter tool without output schema. Minor gap: no description of the successful response structure beyond the null case.
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 the description does not add meaningful detail beyond the schema. The baseline of 3 is appropriate as the description adds no extra parameter insight.
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 the current-live release inventory for a project' with specific verb and resource. It distinguishes from siblings like deploy_release_diff by noting 'Use this before deploy diffs', 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?
Explicitly advises 'Use this before deploy diffs to understand what is currently serving', providing clear context. However, it does not explicitly state when not to use this tool or name alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Diff two release targets for a project. from may be empty, active, or a release id; to may be active or a release id. Returns release-to-release diff buckets and migrations.applied_between_releases. Semantic gateway errors such as invalid targets, same-release diffs, or no active release are preserved.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Diff target: active or a release id. | |
| from | Yes | Diff source target: empty, active, or a release id. | |
| limit | No | Maximum entries per site diff bucket. Gateway default: 1000. | |
| project_id | Yes | Project ID to inspect. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers output and error behavior but doesn't disclose side effects, auth needs, or rate limits. Basic 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?
Two sentences, front-loaded with purpose, no fluff. 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?
Adequately describes return value and error behavior for a tool with no output schema. Could elaborate on diff bucket structure but sufficient.
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 4 parameters with descriptions. Description adds extra meaning by specifying valid values for 'from' and 'to' and mentioning 'limit' default, going 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 verb 'diff', resource 'release targets', and scope 'for a project'. Specifies valid values for parameters, distinguishing it from sibling tools like deploy_release_active.
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 clear context on parameter values and mentions error preservation. Lacks explicit alternatives or when-not-to-use, but sufficient for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a release inventory by id. Returns release metadata, effective/desired state kind, site path inventory, function inventory, secret keys, subdomains, and applied migrations. Use site_limit to cap large site inventories. Canonical SDK errors are preserved.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID that owns the release. | |
| release_id | Yes | Release ID to inspect, e.g. rel_... | |
| site_limit | No | Maximum site path entries to include. Gateway default: 5000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It notes that canonical SDK errors are preserved and implies a read-only operation by stating 'Fetch'. However, it does not explicitly declare safety, rate limits, or authentication requirements, making it adequate but not thorough.
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 front-loaded sentences: purpose, return list, usage tip, and error behavior. No fluff, 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?
Given no output schema, the description explicitly lists all returned fields (metadata, state kind, inventories, etc.) and explains site_limit usage. Error handling is mentioned. This covers most necessary context for a fetch tool, though some format details are omitted.
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 covers 100% of parameters with descriptions, setting a baseline of 3. The description adds extra context for site_limit ('Use site_limit to cap large site inventories') but does not enhance the meaning of project_id or release_id 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 'Fetch a release inventory by id', using a specific verb and resource. It lists the returned fields, distinguishing it from sibling tools like deploy_list (which lists releases) and deploy_release_diff (which compares). No tautology.
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 such as deploy_list or deploy_release_active. The description only offers a usage tip for site_limit but lacks comparative context or when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a deploy operation that ended in activation_pending or schema_settling (e.g. transient gateway failure between SQL commit and the pointer-swap activation). The gateway re-runs only the failed phase forward — SQL is never replayed. Idempotent: calling on an already-terminal operation returns the snapshot without re-running.
| Name | Required | Description | Default |
|---|---|---|---|
| operation_id | Yes | Operation id returned by a prior `deploy` call. Required. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: idempotency, that only the failed phase is re-run, that SQL is never replayed, and the outcome when called on an already-terminal operation. This is good but could mention return value structure.
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-loading the key condition and purpose. Every sentence contributes meaningful information without any fluff or repetition.
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 single parameter and no output schema, the description covers the essential context: states to resume from, idempotency, and a typical failure scenario. It lacks details on possible errors or return format, but these are not critical for agent invocation.
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 (operation_id) described as 'Operation id returned by a prior `deploy` call. Required.' The description adds no new information about the parameter beyond what the schema provides, justifying the baseline score 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 resumes a deploy operation that ended in specific states ('activation_pending' or 'schema_settling'), using specific verbs and resource. It distinguishes from siblings by defining its precise role in the deploy lifecycle, even without explicit comparison.
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 clear conditions for use (resuming a deploy in certain states) and includes a concrete example (transient gateway failure). However, it does not explicitly contrast with other deploy tools or state when not to use it, though the context implies its specific utility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploy a static site (HTML/CSS/JS) from inline file bytes. Files are staged to a temp directory, then uploaded via the v1.32 plan/commit transport — only bytes the gateway doesn't already have are PUT. Served at a unique URL via CloudFront. Free with active tier.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | Array of files to deploy. Must include at least index.html. | |
| target | No | Deprecated/unsupported: unified deploy v2 does not support deployment target labels. Passing this field returns an error. | |
| project | Yes | Project ID to link this deployment to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It explains files are staged, uploaded incrementally (only missing bytes), and served via CloudFront. It also notes pricing ('Free with active tier'). Could mention auth or rate limits but provides good behavioral context for a static deploy.
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, each adding value: what it does, how it works, and cost. No wasted words, major points upfront.
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 and 3 parameters, the description covers the deployment process, transport mechanism, and result (unique URL via CloudFront). Could mention project requirement but described in schema. Lacking error handling or edge cases, but adequate for a simple 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 parameters are already documented. The description adds that files are 'inline file bytes' but doesn't elaborate on parameter details beyond what the schema provides. 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 states 'Deploy a static site (HTML/CSS/JS) from inline file bytes' with specific verb and resource. It details the process of staging, uploading via plan/commit transport, and serving via CloudFront, differentiating it from sibling tools like deploy_site_dir which likely use directory paths.
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 explicit guidance on when to use this tool versus alternatives such as deploy_site_dir or deploy_function. The description implies it is for static sites with inline files but lacks when-to-use or when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deploy a static site from a local directory. Walks the tree, hashes each file, and uploads only the bytes the gateway doesn't already have via the v1.32 plan/commit transport. Files named .git, node_modules, or .DS_Store are skipped; symlinks are rejected. Re-deploying an unchanged tree issues no S3 PUTs. Free with active tier.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | Yes | Local directory to deploy. The SDK walks this directory, hashes each file, and uploads only bytes the gateway doesn't already have via the unified deploy primitive (CAS-backed). Files named .git, node_modules, or .DS_Store are skipped. Symlinks are rejected. | |
| target | No | Deprecated/unsupported: unified deploy v2 does not support deployment target labels. Passing this field returns an error. | |
| project | Yes | Project ID to link this deployment to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses key behavioral traits: only uploads missing bytes, skips .git/node_modules/.DS_Store, rejects symlinks, and issues no PUTs on unchanged trees. It does not cover error handling or permissions, but is fairly transparent for a deployment tool.
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 at four sentences, front-loading the purpose. It avoids redundancy but could be more structured (e.g., listing constraints clearly). 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 no output schema, the description explains input, process, and constraints. It covers what happens (incremental uploads, file skipping) but omits return value or deployment URL. Still, it is complete enough for a tool with standard output expectations.
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 detailed parameter descriptions that largely mirror the tool description. The tool description adds little beyond the schema, such as the transport version and pricing context, but does not significantly enhance parameter understanding.
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 'Deploy a static site from a local directory' and details the process of walking the tree, hashing, and incremental uploads. It distinguishes itself from sibling tools like deploy_site and deploy_function by specifying the local directory source and transport 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 does not explicitly state when to use this tool vs. alternatives. While it implies use for static site deployment from a local path, it lacks guidance on when not to use it or comparisons with other deploy tools like deploy_site.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify gateway/edge release coherence for a deploy operation. Returns the canonical edge-coherence report, including pointer-update state, probed paths, stale-release evidence, and next actions. Set wait=true to poll until coherent or timeout_seconds elapses.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Poll until coherent or timeout. Defaults to false. | |
| project_id | Yes | Project ID that owns the operation. Required (apikey-gated endpoint). | |
| operation_id | Yes | Operation id returned by a prior `deploy` call. Must start with `op_`. | |
| timeout_seconds | No | Maximum seconds to wait when `wait` is true. Defaults to 60. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the return report contents and the polling behavior of wait. However, it does not mention side effects, authentication requirements (beyond what schema provides), or rate limits, leaving some gaps for a read-heavy verification tool.
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 efficiently deliver the purpose, return value, and a key usage hint. No filler or redundancy, and the most critical information 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?
For a tool with no output schema, the description partially compensates by listing report components. However, it lacks details on return structure, error handling, or prerequisites beyond what schema provides. It is adequate but not thorough.
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 the description adds minimal extra meaning beyond the schema definitions. The only slight addition is clarifying that `timeout_seconds` applies when `wait` is true, but that is already implied by schema. The description does not significantly enhance parameter understanding.
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 (verify) and resource (gateway/edge release coherence). It distinguishes this tool from siblings like deploy, deploy_rehearse, and deploy_diagnose_url by its specific purpose of verifying coherence and returning a detailed report.
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 this tool is used after a deploy to check coherence, but it does not explicitly compare to alternatives like deploy_release_active or deploy_diagnose_url. It provides some guidance on the wait parameter but lacks clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the live CDN state for a public blob URL (probed once from gateway-us-east-1 — NOT a global view). Use this when a deployed asset shows the wrong version or you suspect cache staleness. The result includes expectedSha256 (from gateway DB), observedSha256 (what CloudFront just served), recent invalidation status, and a human-readable hint with actionable next-steps. The probeMayHaveWarmedCache: true field warns that the probe itself populates the cache, so subsequent reads from elsewhere may differ. URLs outside the requesting project return 403; non-*.run402.com URLs return 400 unless they're on one of your active custom domains.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Full blob URL (e.g. https://app.run402.com/_blob/avatar.png) | |
| project_id | Yes | Project ID that owns the URL |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: the probe is from a single region, the probe may warm the cache (probeMayHaveWarmedCache), and errors for unauthorized or invalid URLs. This provides strong transparency about side effects and limitations.
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, well-structured paragraph that front-loads the core function, then adds usage, output details, and caveats. Every sentence contributes value 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?
The description covers input parameters, output fields (even without output schema), error cases, and behavioral notes. It is comprehensive for a diagnostic tool, though it does not compare with sibling tools like 'deploy_diagnose_url'.
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 for both parameters (project_id, url). The description adds context about the probe location and output fields, but does not enhance parameter semantics beyond what schema already provides, warranting a baseline score 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 returns live CDN state for a public blob URL, specifies it's from a single region (gateway-us-east-1), and contrasts with a global view. It also mentions specific output fields, making the purpose very 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?
The description explicitly tells when to use this tool (wrong version, suspected cache staleness) and provides error conditions (403 for unauthorized projects, 400 for invalid domains). It does not explicitly reference sibling tools, but the guidance is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Activate custom mailbox addresses once ProjectDomain receive checks have passed. This switches addresses from managed fallback to the custom domain.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It explains the state change (activation and switching) but does not mention prerequisites, permissions, side effects, or error conditions for a mutation tool.
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 sentences, front-loaded with the action and condition. No wasteful wording.
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 lacks explanation of return values or errors. It mentions a prerequisite but does not reference sibling check tools for a complete workflow.
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. The tool description adds context for the domain parameter (checks passed) but does not significantly enhance 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 clearly states the verb (activate), resource (custom mailbox addresses), and the condition (after checks pass) and effect (switch from fallback to custom domain). It distinguishes from sibling tools like domains_apply or domains_check.
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 when to use ('once checks have passed'), providing clear context for sequencing. However, it does not explicitly exclude misuse or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply safe provider-managed ProjectDomain changes when authority is available. Manual-DNS domains return a typed next action instead of mutating external DNS.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden for behavioral disclosure. It hints that manual-DNS domains do not mutate external DNS, implying provider-managed ones do, but it lacks details on side effects, permissions, reversibility, or response format. Minimal 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 a single, clear sentence that front-loads the primary purpose and adds a crucial distinction. It is concise without waste, though splitting could slightly improve readability.
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, no annotations, and a tool that likely has side effects, the description lacks key context: what 'apply' entails, prerequisites, return value details, and error scenarios. It explains two domain types but leaves significant gaps for an agent to use safely.
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 (domain and project_id). The tool description adds no additional parameter-specific meaning. Baseline score of 3 is appropriate as the schema already documents all 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 that the tool applies provider-managed ProjectDomain changes when authority is available, contrasting with manual-DNS behavior. The verb 'apply' and resource are specific, and it distinguishes from sibling domain tools by referencing authority and manual-DNS, though 'changes' could be more explicit.
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 when to use (authority available for provider-managed domains) and hints at an alternative for manual-DNS (which returns a typed next action), but it does not explicitly name sibling tools or state when not to use. This provides moderate guidance but lacks clear boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-observe DNS/provider state for a ProjectDomain and return the current checks. Useful as a preflight and drift detector before validation cycles.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates a re-observation action (potentially making external DNS queries) but does not disclose whether it has any side effects or modifies state. Lacks full behavioral disclosure.
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 with front-loaded action. Every word adds value; no redundancy or wasted text.
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 and complex domain, description provides essential context (preflight, drift detection). Could elaborate on what 'checks' returns, but overall sufficient for basic usage.
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 100% of parameters with descriptions. The description adds no additional meaning beyond what the schema already provides, meeting the baseline.
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 the verb 're-observe' and resource 'DNS/provider state for a ProjectDomain', differentiating it from siblings like `domains_get` which likely returns current state without re-observing.
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 'Useful as a preflight and drift detector before validation cycles', providing clear context for use. However, it does not mention when not to use or explicitly compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disconnect a ProjectDomain from the project and return mailbox addresses to managed fallback.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description mentions 'return mailbox addresses to managed fallback' but does not clarify whether the operation is destructive, reversible, or requires permissions. This leaves behavioral uncertainty.
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 (14 words) that efficiently conveys the core action. It is appropriately concise, though a slightly more structured format could improve clarity.
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?
With no output schema and simple parameters, the description provides adequate context for a straightforward disconnect operation. However, it lacks details about the fallback process and potential side effects.
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 covers both parameters with clear descriptions (domain and project_id). The tool description adds no additional meaning beyond the schema, so a 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 the action ('Disconnect a ProjectDomain'), the resource ('ProjectDomain'), and a specific outcome ('return mailbox addresses to managed fallback'). This distinguishes it from sibling tools like domains_activate or domains_list.
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 explicit guidance on when to use this tool versus alternatives. The description omits context such as prerequisites or scenarios where disconnecting is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a project-scoped ProjectDomain desired state for web, email sending, inbound receive, mailbox addresses, and activation. Returns the aggregate with checks, DNS records, and next actions.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| desired | Yes | Desired ProjectDomain state: web, email.send, email.receive, mailbox_addresses, and activation. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description should disclose behavioral traits. It mentions returning checks, DNS records, and next actions, indicating verification steps. However, it does not mention potential destructiveness, authentication needs, or rate limits, leaving significant gaps for a mutation tool.
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 with no filler. First sentence states purpose, second states output. Slightly verbose but efficient 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?
For a tool with 3 parameters and no output schema, the description covers purpose, scope, and return value. It is mostly complete but could mention prerequisites or when to use this tool vs other domain siblings.
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 baseline is 3. The description adds context by listing aspects (web, email, etc.) but mostly repeats schema field descriptions. It does not provide additional parameter semantics 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 creates or updates a project-scoped ProjectDomain desired state for web, email sending, inbound receive, mailbox addresses, and activation. This verb+resource combination distinguishes it from sibling tools like domains_activate or domains_check.
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 for setting or updating domain configuration but does not explicitly state when to use this over alternatives like domains_activate or domains_apply. No exclusions or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one ProjectDomain aggregate with desired, observed, effective, DNS records, checks, and next actions.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden of behavioral disclosure. It details what data is returned (desired, observed, effective, DNS records, checks, next actions), indicating a read operation. It does not mention potential side effects, but the description is sufficiently transparent for a read tool.
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 with no redundant words. It is front-loaded with the action and then details the returned data. Every word is necessary and contributes to understanding.
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 required params, no output schema), the description adequately conveys the purpose and return data. It could mention error cases or empty results, but overall it provides sufficient context for an AI agent to use 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 coverage is 100% with clear descriptions for both required parameters ('domain' and 'project_id'). The description does not add additional semantic meaning beyond what the schema already 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 action ('Get') and the resource ('one ProjectDomain aggregate') with specific included fields (desired, observed, effective, DNS records, checks, next actions). It distinguishes this tool from sibling domain tools like 'domains_list' (which likely returns multiple) and action-oriented tools like 'domains_activate'.
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 that this tool should be used when you need detailed aggregate information for a single domain, contrasting with 'domains_list' for multiple. However, it does not explicitly state when not to use it or mention alternatives for other domain operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all ProjectDomain aggregates for a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only says 'List all', but does not mention pagination, ordering, filtering, rate limits, or any side effects. This is insufficient for a listing operation.
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 concise sentence that communicates the core purpose with no unnecessary words. It is 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 tool lacks an output schema and the description does not clarify the return format or pagination behavior. For a list tool, this leaves important context incomplete.
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 already fully describes the single parameter 'project_id' with a clear description. The tool description adds no additional semantic value beyond what the schema provides.
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 ('List'), the resource ('ProjectDomain aggregates'), and the scope ('for a project'). It effectively distinguishes from sibling tools like 'domains_get' or 'domains_activate'.
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 such as 'domains_get' (for a single domain) or other listing tools. No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Repair Run402-owned ProjectDomain infrastructure, such as missing SES receipt-rule recipients, without changing external DNS.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description reveals it repairs without touching DNS and gives an example, but it lacks disclosure on side effects, required permissions, error scenarios, or whether the operation is safe to re-run. The 'repair' term suggests corrective action but doesn't clarify if it's idempotent or destructive.
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 of 18 words, front-loading the purpose and key constraint. No superfluous information; every word contributes to clarity.
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 nested objects, no output schema), the description adequately covers the core behavior and provides an example. However, it could be more complete by explaining what triggers the repair, the expected outcome, or success/error responses, especially since no output schema is provided.
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 already describes both parameters (domain and project_id) with clear examples. The description adds no additional meaning beyond reinforcing that these are part of the infrastructure being repaired, so it meets the baseline for 100% schema coverage.
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 'Repair' and the resource 'Run402-owned ProjectDomain infrastructure', with a concrete example ('missing SES receipt-rule recipients'). It also specifies a notable constraint ('without changing external DNS'), effectively distinguishing it from sibling domain tools like domains_apply or domains_check.
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 when internal ProjectDomain infrastructure is broken (e.g., missing SES recipients) and explicitly states it avoids external DNS changes, hinting at alternatives that modify DNS. However, it does not explicitly state when not to use this tool or name alternative tools for DNS-related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a ProjectDomain receive test token for a mailbox address. Send mail to the returned address/token and poll domains_check for receive readiness.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Local part or address to send the receive test to, e.g. info or info@kysigned.com | |
| domain | Yes | The DNS domain, e.g. kysigned.com | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the flow (create token, send mail, poll) but omits details like token expiration, idempotency, persistence, or side effects. The behavioral traits are somewhat transparent but incomplete.
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 that front-load the action and follow with the procedure. Every word is necessary, and there is no fluff or 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?
For a tool with 3 well-documented parameters and no output schema, the description explains the high-level workflow and purpose. However, it lacks details about the return value (the token/address format) and any constraints like validity period, which would enhance completeness.
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 each parameter adequately described. The description adds no additional semantics to the parameters beyond what the schema provides, meeting the baseline but not exceeding it.
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 'Create' and the resource 'a ProjectDomain receive test token' for a mailbox address. It also distinguishes from sibling tools like domains_check by noting that this token is for receive testing and the subsequent polling step. The specific action and workflow are well-defined.
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 clear usage context: create the token, then send mail and poll domains_check for readiness. It implies the tool is for testing email reception. However, it does not explicitly state when not to use it or mention alternatives among the many domain-related siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drain a KMS signer's entire native-token balance to a destination address. Works on suspended signers — the safety valve. Cost: chain gas + $0.000005 KMS sign fee.
| Name | Required | Description | Default |
|---|---|---|---|
| signer_id | Yes | The KMS signer ID | |
| project_id | Yes | The project ID | |
| destination_address | Yes | Where to send the entire native-token balance. Cost: chain gas + $0.000005 KMS sign fee. Works on suspended signers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the cost and the special condition (suspended signers), but does not explain consequences like irreversibility or what happens to the signer after draining. A score of 3 reflects some transparency but missing important behavioral details.
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 the core purpose, second adds context and cost. No fluff, front-loaded, and every word earns its place.
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 covers the main operation, cost, and when to use it (suspended signers). However, it lacks details on edge cases (e.g., non-suspended signers, invalid addresses) and does not describe return values. For a moderate-complexity tool with no output schema, a 3 is adequate.
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 basic descriptions. The tool description repeats cost info for destination_address but does not add significant new meaning beyond the schema. Baseline is 3; slight addition keeps it at 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 action (drain), the resource (KMS signer's entire native-token balance), and the destination address. It also mentions a specific use case (works on suspended signers). This distinguishes it from sibling tools like 'delete_signer' or 'provision_signer'.
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 that it works on suspended signers (the safety valve), providing context for when to use it. However, it does not specify when not to use it or mention any alternatives, though the sibling list suggests no direct alternatives exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Grouped, release-baselined error memory for a project, verdict-first: every page leads with a computed promote-vs-revert verdict (the gateway's numbers — never recomputed here), then the collapsed error identities. The post-promote watch: right after an apply/promote activates a release, call errors_list with new_in set to the just-activated release id (the promote response's next_actions carries a ready-made watch_errors command for the CLI equivalent). verdict.new_fingerprints > 0 means the release introduced NEW error identities — inspect errors[] (each row has samples with request ids + a runnable logs command) and consider reverting; new_fingerprints === 0 with healthy verdict.invocations_in_window means clean under real traffic (0 errors over 0 invocations is absence of signal, not proven health). Filter by since/until/function/kind/fingerprint; pass fingerprint_id to fetch one fingerprint's full detail (all samples + also_seen_in_functions). Quality tier coarse = the function predates the error side-channel; redeploy to upgrade fidelity. Read-only, own-project service-key auth; cursors are opaque.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Restrict to one choke-point class: uncaught | boot_crash | invoke_failed | handled_5xx. | |
| limit | No | Page size (default 50, max 200). | |
| since | No | ISO-8601 window start. Default window is the last 24h (gateway resolves `until` − 24h). | |
| until | No | ISO-8601 window end. Defaults to now (gateway-side). | |
| cursor | No | Opaque `next_cursor` from a prior page. Returns the next page. Never parse cursors. | |
| new_in | No | A release id, or the literal "active" (gateway resolves the live release). Selects error identities FIRST seen under that release and drives the verdict's new_fingerprints / baseline — the promote-gate signal. | |
| function | No | Restrict to one function by name. | |
| project_id | Yes | Project whose errors to read. Authorized with the project's OWN service key; a key for a different project gets 403, never a 404. | |
| fingerprint | No | Restrict the list to one exact fingerprint identity (`fp_…`). | |
| fingerprint_id | No | Fetch ONE fingerprint's full detail (all samples, per-sample fetch_logs commands, also_seen_in_functions) instead of a page. When set, all filter params (since/until/function/kind/fingerprint/new_in/limit/cursor) are rejected. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses read-only, auth requirements, cursor opacity, quality tier meaning, and the change in behavior when fingerprint_id is set (rejects other filters). It also explains the verdict logic and the promote-watch pattern, which is comprehensive for a tool of this complexity.
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, dense paragraph. While front-loaded with the main purpose, it contains multiple clauses and detailed behavioral notes that could be separated for readability. It is adequately concise but not highly 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 the tool's complexity (10 params, no output schema, no annotations), the description covers the core use case (promote-watch), filtering, and special parameter behaviors. It explains the verdict fields and quality tier. However, it does not describe return format or pagination beyond 'cursors are opaque', leaving some ambiguity 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% with descriptions for all 10 parameters. The description adds context beyond parameter list entries, e.g., explaining that new_in selects errors 'FIRST seen under that release' and drives verdict fields, and that fingerprint_id fetches full detail and rejects other filters. This increases semantic value 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: 'Grouped, release-baselined error memory for a project, verdict-first' with specific filtering and detail retrieval. It distinguishes from siblings by describing its unique verdict and promote-watch functionality; no other sibling tool appears to offer this error memory view.
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 usage context, such as calling after an apply/promote to check new error fingerprints, and how to interpret verdict fields. It gives actionable guidance (e.g., 'consider reverting' when new_fingerprints > 0). However, it lacks explicit when-not-to-use scenarios or direct comparisons to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export the supported Run402 Core runtime slice of a Cloud project as a portable .r402ar archive. Can wait for readiness and write the downloaded archive to a local path. Secrets, credentials, billing, allowance, logs, fleet, and Cloud operations are never exported.
| Name | Required | Description | Default |
|---|---|---|---|
| auth | No | Auth export mode. Default stubs; credentials are never exported. | |
| wait | No | Poll until ready. Defaults true when output_path is set, otherwise false. | |
| scope | No | Archive scope. v1 supports portable-runtime-v1. | |
| project_id | Yes | Project ID to export from Run402 Cloud. | |
| timeout_ms | No | Wait timeout in milliseconds. Default 600000. | |
| consistency | No | Consistency mode. Default pause-writes, recorded as cloud_write_pause_v1. | |
| output_path | No | Optional local file path for the downloaded .r402ar archive. When set, the tool waits for readiness and writes bytes here. | |
| idempotency_key | No | Retry-safe idempotency key for archive creation. | |
| poll_interval_ms | No | Polling interval in milliseconds. Default 1000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors (wait, local write) and explicitly states what is never exported (secrets, credentials, etc.), but does not explicitly declare read-only nature or authorization needs.
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 sentences that front-load the main purpose and add critical context without unnecessary 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 9 parameters and no output schema, the description is minimal. It explains the local write path but does not describe return value when output_path is absent, nor detail the 'wait for readiness' mechanism beyond what parameters cover.
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 3. The description does not add significant meaning beyond schema; it mentions wait and output_path but the schema already describes them adequately.
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 exports a Runtime slice as a .r402ar archive, specifies it can wait and write locally, and lists what is never exported, distinguishing it from siblings like import/inspect.
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 creating portable archives but does not explicitly state when to use this tool versus alternatives like import or inspect, nor provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fork a published app into a new project. Creates a full copy including database, functions, site, and optionally claims a subdomain.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new forked project | |
| subdomain | No | Optional subdomain to claim for the forked app | |
| version_id | Yes | The app version ID to fork (from browse_apps) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It states the tool creates a full copy and optionally claims a subdomain, which implies non-destructive behavior, but it does not mention auth requirements, rate limits, or consequences if the subdomain is taken.
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 long, front-loaded with the core action, and contains no redundant information. 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 3 parameters and no output schema, the description covers the main purpose and key aspects. It could mention error cases (e.g., invalid version_id) or the result (e.g., new project ID), but overall it provides sufficient context 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% with each parameter described. The description adds minimal extra meaning beyond the schema, such as clarifying subdomain is optional, but this is already evident from the 'required' list. No deeper insights into parameter values or constraints.
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 identifies the tool's action ('Fork a published app into a new project') and specifies what it includes (database, functions, site, optionally a subdomain). This distinguishes it from siblings like 'publish_app' or 'delete_project'.
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 (creating a copy of a published app) but does not provide explicit when-to-use or when-not-to-use guidance. No mention of alternatives like 'import_project_archive' or 'export_project_archive' that might serve similar purposes in different contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh function(s) onto the platform's current entry wrapper + bundled runtime WITHOUT changing source (capability function-runtime-rebuild, gateway v1.69+). Provide name to rebuild one function, or omit it to rebuild every function in the project. Re-bundles from each function's STORED source with deps pinned to the recorded exact versions, so the source code_hash is unchanged and no new release is created — this is how a gateway-side wrapper fix (e.g. an SSR auth.* fix) reaches an already-deployed function (a plain redeploy with unchanged source does NOT pick it up). Strictly opt-in; the platform never auto-rebuilds. Wallet-authed (project ownership; no service key) and allowed during billing grace. Functions deployed before dependency locking return CANNOT_REBUILD_UNLOCKED_DEPS — redeploy them from source with deploy_function. Use list_functions (runtime_stale) or run402 doctor to find stale functions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Function name to rebuild. Omit to rebuild every function in the project (batch). | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers behavioral traits: no source change, no new release, re-bundles with pinned deps, picks up wrapper fixes, strict opt-in, auth requirements, and error case for unlocked deps.
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 verbose but well-structured, front-loaded with key action, and each sentence adds value. Could be slightly more concise but appropriate for 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?
Covers action, preconditions, error conditions, and related tools, but does not describe return values since no output schema exists. Comprehensive given tool simplicity.
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 parameter descriptions. Description adds significant context for 'name' (optionality, batch behavior) beyond what the schema provides, adding clear 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 clearly states the tool refreshes functions onto the current wrapper/bundled runtime without changing source, distinguishing it from redeployment and sibling tools like deploy_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?
Explicitly states when to use (wrapper fixes), when not to (unlocked deps, suggesting deploy_function), and provides context (opt-in, wallet-authed, billing grace allowed). Also points to list_functions to find stale functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a PNG image from a text prompt. Costs $0.03 USDC via x402. Aspect ratios: square (1:1), landscape (16:9), portrait (9:16).
| Name | Required | Description | Default |
|---|---|---|---|
| aspect | No | Aspect ratio: square (1:1), landscape (16:9), portrait (9:16) | square |
| prompt | Yes | Image description. Max 1000 characters. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses the cost and that the output is a PNG image. The prompt length limit is inherited from the schema. It does not mention error handling or idempotency, but for a generative tool this is reasonable.
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 sentences: first states purpose, second adds cost and aspect ratios. No extraneous information. Front-loaded with the core action.
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 does not explain the return format (e.g., URL or base64). It covers key usage constraints (cost, aspect ratios) and input limits. Missing response details, but acceptable for a simple generation 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%. The description repeats the aspect ratio enum and the prompt length, adding no new semantic information beyond the schema fields. 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 'Generate a PNG image from a text prompt,' which specifies the verb, resource, and input. It is distinct from sibling tools (no other image generation tools). Includes additional details like cost and aspect ratios.
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 mentions a cost of $0.03 USDC via x402, which is a key usage constraint. It also lists available aspect ratios. However, it does not explicitly state when not to use or mention alternatives, but no alternatives exist in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current agent contact assurance state: wallet_only, email_pending, email_verified, passkey_pending, or operator_passkey.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral aspects. It correctly indicates a read-only operation but lacks details on authentication, rate limits, or what happens if no contact is set. The returned states are listed, which helps, but more context would be beneficial.
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, well-structured sentence that immediately conveys the purpose and possible outputs. No unnecessary 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 trivial complexity (no parameters, no output schema), the description adequately tells an agent what to expect. It could mention the subject 'current agent' but the meaning is implicit. Missing some context about when to use, but acceptable for a simple getter.
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 tool has no parameters, so the schema provides full coverage. The description adds no parameter info, which is appropriate. A baseline of 4 is justified for zero-parameter tools.
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 ('Get'), the resource ('agent contact assurance state'), and explicitly lists all possible return values. It is specific and distinguishes itself from sibling tools that modify or verify contact.
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 like set_agent_contact or verify_agent_contact_email. The description does not indicate prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a specific published app — details, required secrets, fork pricing.
| Name | Required | Description | Default |
|---|---|---|---|
| version_id | Yes | The version ID of the app to inspect |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. 'Inspect' suggests read-only, but no explicit confirmation of non-destructive behavior or authorization requirements.
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, front-loaded with key verb, no unnecessary words. Efficient and clear.
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?
Adequate for a simple get tool with one parameter and no output schema. Lists key return aspects, though response format is not described.
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?
Only parameter 'version_id' is documented in schema; description adds value by listing what the response includes (details, secrets, pricing), going 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?
Description clearly states verb 'inspect' and resource 'specific published app', listing included details like secrets and pricing. Distinguishes from siblings like browse_apps.
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?
Implies use for a single app via 'specific', but lacks explicit when-to-use vs alternatives like browse_apps or fork_app.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a previously submitted contract call by call_id. Returns lifecycle state (pending/confirmed/failed), block number, gas used, gas cost in USD-micros, receipt, and any error.
| Name | Required | Description | Default |
|---|---|---|---|
| call_id | Yes | The contract call ID (ccall_...) | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists the return fields (lifecycle state, block number, gas used, etc.), which adds behavioral insight. However, it does not explicitly disclose that this is a read-only operation, nor does it mention any side effects or prerequisites. Given no annotations, more transparency would be beneficial.
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 with no wasted words. It front-loads the action and lists return values efficiently.
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 simple lookup tool with two parameters, the description adequately covers purpose and return values. However, the lack of output schema is compensated by listing return fields. Minor gap: no mention of error structure.
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 both parameters well-described. The description adds 'by call_id' but does not provide additional meaning beyond the schema. This meets the baseline for high coverage.
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 'Look up a previously submitted contract call by call_id,' providing a specific verb and resource. This distinguishes it from sibling tools like contract_call or contract_read, which have different purposes.
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 is given on when to use this tool versus alternatives. The description simply states what it does without providing context for appropriate usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a sent email with details and any replies.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| message_id | Yes | The message ID to retrieve | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates a read operation but fails to disclose authentication requirements, error handling, or behavioral details like what happens if the email does not exist or what 'details' entails. Minimal behavioral insight.
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 with no unnecessary words. It is front-loaded with the verb and resource, making it efficient and easy to parse.
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 lack of output schema and only three parameters, the description is too sparse. It omits return value format, error conditions, and how replies are included. A more complete description would cover these aspects.
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 each parameter is documented in the schema. The tool description adds no extra meaning beyond what the schema already provides. Baseline 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 the action ('Get') and the resource ('a sent email with details and any replies'), which is specific and distinguishable from siblings like get_email_raw (raw source) or list_emails (listing all). However, it does not explicitly differentiate itself, so it earns a 4.
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 no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. The agent receives no help in deciding between this and sibling tools like get_email_raw or list_emails.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the raw RFC-822 bytes of an inbound email message, base64-encoded. The decoded bytes are bit-identical to the DKIM-signed original — no parsing, normalization, or CRLF cleanup. Use this for cryptographic verification (DKIM checks, zk-email proofs). Inbound messages only; outbound returns 404. For display/threading, use get_email instead.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| message_id | Yes | The message ID to retrieve raw bytes for (must be an inbound message) | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description holds full burden. It discloses that bytes are base64-encoded, bit-identical to DKIM original, no parsing/normalization/CRLF cleanup, inbound-only, and outbound returns 404. However, it does not specify the response format (e.g., JSON wrapper) or other error conditions.
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, no fluff. First sentence states function, second adds key behavioral detail, third provides usage guidance and alternative. Every sentence earns its place.
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 covers purpose, usage, and key behavioral constraints. Missing details about response structure (e.g., JSON wrapping) and error handling beyond outbound 404, but overall adequate for a simple retrieval 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 clear descriptions for all three parameters. The description repeats schema info (e.g., 'must be an inbound message') without adding new meaning. 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 states 'Get the raw RFC-822 bytes of an inbound email message, base64-encoded' which clearly identifies the verb (get) and resource (raw bytes of inbound email). It distinguishes from sibling tool 'get_email' by specifying that this is for raw bytes vs. display/threading.
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 use cases: 'Use this for cryptographic verification (DKIM checks, zk-email proofs)' and when not to use: 'Inbound messages only; outbound returns 404' and 'For display/threading, use get_email instead'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current authorization manifest for a project (GET /projects/v1/admin/:id/expose). Returns the last-applied manifest from internal.project_manifest, or a manifest reconstructed by introspecting live DB state if none has ever been applied. The source field is "applied" or "introspected".
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, so description must carry full burden. It discloses two return sources (applied vs introspected) and the source field, providing useful behavioral context for a read-only operation. Missing error handling or permission details but adequate.
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, front-loaded with purpose and behavior. Every sentence adds value with no redundancy or 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?
For a simple read tool with one parameter and no output schema, description explains both return paths and the source field. Could detail manifest structure but 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?
Schema coverage is 100% for the single parameter project_id. Description adds no additional meaning beyond the 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?
Clearly states it retrieves the current authorization manifest for a project, distinguishing it from siblings like apply_expose (which applies) and validate_manifest (which validates). Includes endpoint and behavior details.
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?
Implies usage for reading the current manifest but lacks explicit guidance on when to use this vs alternatives like apply_expose or validate_manifest. No 'when-not' or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent logs from a deployed function. Shows console.log/error output and error stack traces from CloudWatch.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Function name to get logs for | |
| tail | No | Number of log lines to return (default: 50, max: 1000) | |
| since | No | Only return logs at or after this ISO 8601 timestamp (e.g. 2026-03-29T14:00:00Z). Invalid timestamps are rejected before the API call. | |
| project_id | Yes | The project ID | |
| request_id | No | Only return logs correlated to this routed request id, function run id, or attempt id, such as req_abc123, fnrun_abc123, or fnatt_abc123. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the tool is a read operation and what it shows, but does not disclose side effects, error handling, rate limits, or the format of the output. For a tool with zero annotations, this is insufficient.
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 sentences, no wasted words, and front-loaded with the core action and output. Efficient and to the point.
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 covers the basic purpose but lacks depth. With 5 parameters and no output schema, it would benefit from explaining the 'since' and 'request_id' filters, or the structure of the returned logs. The schema fills some gaps, but overall, the description is minimal for the tool's 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 description coverage is 100%, so the baseline is 3. The description adds no additional meaning about the parameters (name, tail, since, project_id, request_id) beyond what the schema already provides. It does not compensate with extra context about CloudWatch integration or parameter usage.
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 'get' and resource 'recent logs from a deployed function', and specifies the output includes console.log, errors, and stack traces. However, it does not explicitly distinguish from the sibling tool 'get_function_run_logs', which has a similar purpose.
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 like 'get_function_run_logs' for run-specific logs. There are no when-not-to-use or prerequisite instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one durable function run by fnrun_ id.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | Function run id, fnrun_... | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states the fetch operation without disclosing safety (e.g., read-only nature), error handling, rate limits, or auth requirements. This is minimal 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 a single 9-word sentence that is front-loaded with the verb and resource. Every word is necessary and contributes to clarity with 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?
For a simple fetch tool with no output schema, the description is adequate but lacks details about the return value (e.g., full run object), error conditions, and no behavioral context from annotations. It covers the basic operation but is not thorough.
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% with both parameters described. The description adds 'one durable function run by fnrun_ id', slightly reinforcing the run_id format, but adds little 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 verb 'Fetch' and the resource 'one durable function run', specifying identification by 'fnrun_ id'. It distinguishes from sibling tools like 'list_function_runs' (listing) and 'cancel_function_run' (cancellation).
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 explicit when-to-use or when-not-to-use guidance is provided. The description only implies retrieval of a specific run, and the sibling context suggests use when a single run is needed, but alternatives like 'list_function_runs' are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch logs correlated to one durable function run.
| Name | Required | Description | Default |
|---|---|---|---|
| tail | No | Number of log entries to return (default 50, max 1000). | |
| since | No | Only include logs at or after this ISO timestamp or epoch ms. | |
| run_id | Yes | Function run id, fnrun_... | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states 'correlated logs' but does not disclose whether the operation is read-only, if it requires specific permissions, what happens if the run does not exist, or any side effects. The description is insufficient for an unannotated tool.
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, concise sentence that is front-loaded with the key action and resource. No extra words or redundancy. 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?
The tool has no output schema and four parameters. The description does not explain the return format, pagination behavior (though 'tail' suggests it), or error conditions. For a simple fetch tool, this missing context makes it less complete than it could be.
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% (all 4 parameters have descriptions in the schema). The tool description adds no additional meaning beyond the schema; it just restates the purpose. Baseline 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 the action ('Fetch') and the resource ('logs correlated to one durable function run'). It is specific and distinguishes this tool from sibling tools like 'get_function_logs' (generic) and 'get_function_run' (single run details).
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 no guidance on when to use this tool versus alternatives like 'get_function_logs' or 'get_function_run'. There is no mention of prerequisites, typical use cases, or when not to use it. This leaves the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the project's mailbox info (ID, address, slug, default/readiness metadata, and footer-policy fields when returned). Use to check if a mailbox exists.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox (otherwise returns an ambiguity error naming the slugs). | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description includes return fields but does not mention idempotency, permissions, or error behavior (e.g., 404 if not 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?
Two concise sentences with clear structure: what it returns and why to use it.
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?
No output schema; description covers main returned fields but omits error conditions and structure 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%; description adds no extra parameter info beyond the schema (though it lists response fields).
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 retrieves mailbox info (ID, address, slug, etc.) for a project, distinguishing it from siblings like create_mailbox or list_mailboxes.
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 explicit use case ('check if a mailbox exists'), but does not mention when to use an alternative like list_mailboxes or exclude misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific webhook by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID | |
| webhook_id | Yes | The webhook ID (whk_...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the burden. It indicates a read operation ('get details') but does not mention authentication requirements, error handling (e.g., webhook not found), or rate limits. Basic transparency is present but leaves gaps.
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 short sentence that conveys the essential purpose without any filler. Every word is meaningful and necessary.
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 simple retrieval tool without an output schema, the description covers the core functionality adequately. It could optionally mention return fields or error conditions, but completeness is sufficient given the tool's simplicity and the presence of a sibling list tool for context.
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 each parameter has a description. The description adds no additional meaning beyond what the schema provides. Baseline 3 is appropriate as the schema already documents parameter purposes adequately.
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 'Get details of a specific webhook by ID', which is a clear verb+resource pair. It distinguishes from sibling tools like list_mailbox_webhooks (which lists all) by specifying retrieval by ID.
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 gives no explicit guidance on when to use this tool versus alternatives (e.g., list_mailbox_webhooks for listing). Usage is implied by 'by ID', but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the operator's notification preferences (channels, cadence, threshold/lifecycle/security toggles, locale, timezone).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only states it reads preferences. It does not disclose any behavioral traits like authentication requirements or side effects, but the read nature is transparent.
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, front-loaded with the verb and resource, and efficiently lists all relevant preference aspects. 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?
Despite no output schema, the description covers the high-level content of preferences. It does not specify return format but is sufficient for a simple read 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% (no parameters). The description adds meaning by listing the preference categories, providing context beyond the empty 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 reads the operator's notification preferences and lists specific categories (channels, cadence, toggles, locale, timezone), distinguishing it from sibling tools like set_notification_preferences and list_notifications.
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 viewing current preferences, but does not explicitly state when to use versus alternatives or provide exclusions. However, the context is clear enough for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compact operator-health snapshot: contact assurance, critical items, skipped notifications, organizations, projects, active thresholds. Read via run402 doctor.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as read-only nature, side effects, or access requirements beyond the cryptic note 'Read via run402 doctor'.
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 short but includes a cryptic instruction ('Read via run402 doctor') that may confuse the agent. Could be more streamlined.
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 and zero parameters, the description lists content items but lacks details on output structure. Adequate for a simple snapshot 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?
Input schema has zero parameters, so schema coverage is 100%. Baseline score of 3 applies, and description adds no parameter-specific meaning as none exist.
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 provides a compact operator-health snapshot, listing key components (contact assurance, critical items, etc.), and distinguishes from sibling tools like service_health by focusing on operator-specific items.
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 like service_health or service_status. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one organization (GET /orgs/v1/:org_id) — its org_id, display_name, tier, lease_started_at, lease_expires_at, and your role. Any active member may read; a non-member (including a guessed id) gets the same non-revealing 403. Params: org_id.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The org id, e.g. `org_...`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses the non-revealing 403 error for non-members and that any active member can read. It lacks details on rate limits or idempotency, but the behavioral info is good for a simple read operation.
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, using a single sentence to convey the purpose, fields, access rules, and error behavior. Every part 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 the tool's simplicity (one parameter, read-only, no output schema), the description covers key aspects: what it returns, who can use it, and error handling. It could mention idempotency but is largely 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 one parameter. The description states 'Params: org_id' and the schema provides a description. No additional meaning is added beyond repeating the parameter name.
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 'Read one organization', lists the specific fields returned, and includes the HTTP method and path. It distinguishes from sibling tools like list_orgs and create_org.
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 mentions that any active member may read and non-members get a 403, but does not explicitly state when to use this tool versus alternatives like list_orgs for multiple organizations or create_org for creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one project data snapshot and its next actions.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID that owns the snapshot. | |
| snapshot_id | Yes | Snapshot ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only nature, required permissions, or what 'next actions' entails. The burden falls entirely on the description, which is insufficient.
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 very concise with no wasted words, but it could include more useful context without becoming verbose. It is front-loaded and 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?
The description lacks detail about the return value format or the nature of 'next actions.' Given the sibling tools around snapshots, more context would help an agent understand the tool's role.
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 both parameters documented in the schema. The description adds no additional meaning beyond the schema's descriptions, so a 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 the tool retrieves a single project snapshot and its next actions, distinguishing it from siblings like list_project_snapshots, create_project_snapshot, or restore_project_snapshot.
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 is provided on when to use this tool versus alternatives, such as list_project_snapshots for multiple snapshots or restore_project_snapshot for restoration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tier pricing for Run402 projects. Free, no auth required. Shows prices, lease durations, storage limits, and API call limits.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description implies a read-only, non-destructive operation by stating 'Get tier pricing'. It also discloses that it is free and requires no authentication. However, it does not explicitly state that it does not modify state or mention 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 a single sentence that is front-loaded with the purpose and includes all necessary information without any 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 that there is no output schema, the description adequately explains the return values by listing the key data fields. This is sufficient for a simple query tool with no parameters.
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 tool has no parameters (schema coverage 100%), so the description's role is to explain what the tool returns. It adds value by listing the specific data fields: prices, lease durations, storage limits, and API call limits.
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 gets tier pricing for Run402 projects, specifies it's free and no auth required, and lists the specific data returned (prices, lease durations, storage limits, API call limits). This distinguishes it from sibling tools like tier_status.
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 indicates when to use it (free, no auth required, anyone can use), but does not explicitly mention when not to use it or suggest alternatives like tier_status. Nevertheless, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Introspect the database schema — tables, columns, types, constraints, and RLS policies. Useful for understanding the database structure before writing queries.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | The project ID (defaults to the active project) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It describes the output (tables, columns, etc.) and implies a read-only operation, but does not explicitly confirm non-destructive behavior, permissions, or performance characteristics. Adequate but not comprehensive.
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 sentences: first defines the operation, second gives usage context. No wasted words, 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?
Despite lacking an output schema, the description enumerates what is returned (tables, columns, etc.), which is sufficient for this tool. It integrates well with sibling tools and the simple parameter. Minor gap: no mention of output format or limits.
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% (one parameter fully described). The description adds no additional meaning beyond the schema; it does not elaborate on the parameter's use or provide examples. 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 uses a specific verb 'introspect' and clearly identifies the resource 'database schema' with enumerated details (tables, columns, types, constraints, RLS policies). It effectively distinguishes from query-execution siblings like 'run_sql' and 'rest_query'.
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 useful 'before writing queries', providing clear context for when to use. Does not specify when not to use or list alternatives, but the guidance is adequate for a straightforward introspection tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a KMS signer's metadata + live native-token balance + USD-micros (Chainlink-cached price).
| Name | Required | Description | Default |
|---|---|---|---|
| signer_id | Yes | The KMS signer ID (cwlt_...) | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should fully disclose behavior. It mentions 'live native-token balance' and 'Chainlink-cached price', indicating read operations and data freshness. However, it does not explicitly state that this is a read-only operation with no side effects, nor does it mention any necessary permissions or potential errors.
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 efficient sentence that front-loads the core purpose. Every word adds value; there is no fluff or 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?
For a simple getter with two parameters and no output schema, the description adequately covers what the tool returns (metadata, balance, price). It does not mention error cases or what happens if the signer is not found, but overall it is sufficiently 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% with basic parameter descriptions for 'signer_id' and 'project_id'. The tool description does not add extra meaning beyond what the schema already provides, so baseline of 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 uses specific verbs and resources: 'Get a KMS signer's metadata + live native-token balance + USD-micros'. It clearly distinguishes from sibling tools like 'list_signers' (which lists all signers) and 'delete_signer'.
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 a specific signer (via signer_id) versus list tools, but it does not explicitly state when to use this tool versus alternatives like 'list_signers' for listing or 'provision_signer' for creating. No when-not or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get project usage report — API calls, storage usage, limits, and lease expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states it's a report (read), but does not disclose safety, auth requirements, side effects, or error handling. For a tool with no annotations, this is insufficient.
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 with dash-delimited list of report contents. Efficiently communicates scope without redundancy or 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?
Despite no output schema, the description lists key report elements (API calls, storage, limits, lease expiry), providing adequate context for a simple read operation. Minor gap: no mention of read-only nature.
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) described as 'The project ID'. Description adds no further meaning beyond the schema, so baseline of 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 clearly states 'Get project usage report' with specific resource enumeration (API calls, storage, limits, lease expiry), distinguishing it from sibling tools like ai_usage.
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 explicit guidance on when to use this tool versus alternatives such as billing_history or ai_usage. The description implies a straightforward read but does not provide context for excluding other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import a verified portable archive into a new local Run402 Core project through the Core gateway. Automatically verifies before import, supports dry_run and require_runnable, and reports SECRET_VALUES_REQUIRED with next actions.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New Core project name. Default imported-project. | |
| dry_run | No | Verify and plan without creating a project. | |
| core_url | No | Core gateway URL. Default RUN402_CORE_URL or http://127.0.0.1:4020. | |
| env_file | No | Env file containing required secret values. | |
| archive_path | Yes | Local archive directory or .r402ar tar path. | |
| secret_values | No | Explicit secret values. Overrides env_file entries for duplicate names. | |
| require_runnable | No | Block import unless required secret values are supplied. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses automatic verification before import, dry_run and require_runnable support, and SECRET_VALUES_REQUIRED reporting. With no annotations, the description provides moderate behavioral context but omits details on error handling, permissions, or side effects like cleanup on failure.
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 with no waste. Purpose is front-loaded, followed by key features. 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 main behavioral aspects (auto-verification, dry_run, require_runnable, secret reporting) but does not describe the return value format or error conditions. For a complex tool with 7 parameters and no output schema, more detail on response behavior would be beneficial.
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 there. The description adds minimal extra meaning beyond mentioning dry_run and require_runnable as features, which is already in the schema. 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?
Clearly states verb (import), resource (verified portable archive), and destination (new local Run402 Core project). Distinguishes from sibling tools like verify_project_archive and inspect_project_archive by indicating it performs import with automatic verification.
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?
Implies usage contexts through mentions of dry_run (to verify only) and require_runnable (to enforce secret provisioning), but lacks explicit comparison to sibling tools or guidance on when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set up agent allowance, request faucet funding, and check tier status — single-call bootstrap. Idempotent, safe to re-run.
| Name | Required | Description | Default |
|---|---|---|---|
| rail | No | Payment rail: x402 (Base Sepolia, default) or mpp (Tempo Moderato) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It declares the tool is 'idempotent, safe to re-run', which is key behavioral information for a tool that performs multiple actions. It lists the actions performed (allowance, faucet, tier status) but does not detail the exact side effects or error conditions.
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 front-loads the key actions and ends with a clear behavioral note. Every word earns its place; there is no fluff. It is optimally concise.
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 combines multiple actions (allowance setup, faucet request, tier check), the description adequately lists them. However, it lacks details about return values, prerequisites (e.g., authentication, project context), and error handling. For a critical bootstrap tool, more completeness is expected.
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 one optional parameter 'rail' with a full description and enum values (100% coverage). The description adds no additional meaning to the parameter beyond what the schema provides. Therefore, the score is at 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 clearly states the tool's purpose: it sets up allowance, requests faucet funding, and checks tier status, all in a single call. The verb 'bootstrap' effectively summarizes the resource being set up. However, it does not differentiate from sibling tools like 'allowance_create', 'request_faucet', and 'tier_status', which perform these actions individually.
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 labels the tool as a 'single-call bootstrap' and notes it is 'idempotent, safe to re-run'. This implies usage for initial setup and indicates it can be run multiple times without harm. However, it does not explicitly state when to use this tool versus calling the individual tools, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Initiate a project transfer (owned-org recipient shape v1.96+). Addressed to a WALLET (to_wallet, completed by accept_project_transfer), an EMAIL (to_email, completed by claim_project_transfer), OR an owned ORG (to_org_id, same-actor move that completes immediately in the first gateway release) — provide exactly one. You must currently own/admin the project; for to_org_id you must be an active owner of both the source and destination orgs. Wallet/email transfers create a pending row with 72h expiry and freeze owner-side mutations until completed, cancelled, or expired. The recipient gets the project under the migrate billing policy. Owner's tier lease is NOT refunded. GitHub repo ownership is NOT transferred. Calls POST /projects/v1/:project_id/transfers.
| Name | Required | Description | Default |
|---|---|---|---|
| message | No | Optional free-text note shown to the recipient in the preview and notification emails. | |
| to_email | No | Recipient EMAIL. Provide EXACTLY ONE of `to_wallet`, `to_email`, or `to_org_id`. An email recipient completes the transfer via `claim_project_transfer` (they claim it into an org they own). | |
| to_org_id | No | Destination ORG id. Provide EXACTLY ONE of `to_wallet`, `to_email`, or `to_org_id`. First gateway release is same-actor only: caller must be an active owner of the source org and destination org. Completes immediately and returns project keys. | |
| to_wallet | No | Recipient WALLET address (any case — the gateway lowercases). Provide EXACTLY ONE of `to_wallet`, `to_email`, or `to_org_id`. A wallet recipient completes the transfer via `accept_project_transfer`. | |
| project_id | Yes | Project id to transfer. You must currently own or admin it (the gateway verifies against fresh DB state). | |
| billing_policy | No | Wallet rail only. Phase 1A supports only `migrate` (default). The project moves into the recipient's organization. | |
| kysigned_record_id | No | Wallet rail only. Optional KySigned record id. Phase 1A stores this verbatim (no verification). | |
| retain_collaborator_role | No | Email rail only (v1.91): keep a `developer` membership in the recipient's org after the transfer completes. The recipient must accept it at claim time (`accept_retained_collaborator`). Omit for a full severance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses multiple behavioral traits: 72h expiry, freeze of owner mutations, no refund of tier lease, no GitHub transfer, billing policy migrate, and immediate completion for org. Minor missing details like what happens on expiry or cancellation, but overall strong.
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 dense paragraph with clear logical flow: purpose, recipient options, prerequisites, side effects, and version notes. 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 8 parameters, no output schema, and no annotations, the description covers purpose, usage, behavior, and parameter semantics comprehensively. It explains all three recipient paths and their consequences. Could mention error handling or expiry behavior in more detail, but overall quite 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%, so baseline is 3, but the description adds significant value beyond the schema: it explains the exclusivity of the three recipient parameters, the pending vs immediate behavior, default billing policy, and the purpose of retain_collaborator_role for email rail.
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 initiates a project transfer and specifies three distinct recipient types (wallet, email, org), each with its own completion path. It distinguishes from sibling tools like accept_project_transfer and claim_project_transfer by describing the flow.
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 each recipient type, prerequisites (must own/admin project, for org must own both orgs), and the behavioral differences (pending row with 72h expiry for wallet/email, immediate completion for org). It contrasts with sibling tools named in the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a local run402-project-archive.v1 directory or .r402ar tar offline. Reports digest, required secrets, auth stubs, export report, portability report, and compatibility diagnostics without Cloud credentials.
| Name | Required | Description | Default |
|---|---|---|---|
| archive_path | Yes | Local archive directory or .r402ar tar path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes what the tool reports but does not explicitly state that it is read-only or whether it modifies any files. The term 'inspect' implies safety, but more explicit behavioral disclosure (e.g., no side effects) would improve 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 a single sentence that efficiently packs all relevant information: target, reports produced, and key condition (no credentials). No unnecessary 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 has only one parameter and no output schema, the description provides a good overview of what the tool does and what it returns. It could be more explicit about the return format (e.g., JSON) but is largely 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% and the description essentially repeats the schema's description of archive_path. No additional semantic detail is added beyond what the schema already provides.
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 'Inspect' and the resource 'local archive directory or .r402ar tar offline'. It lists the reports produced (digest, secrets, etc.) and distinguishes from sibling tools like export_project_archive and verify_project_archive by emphasizing offline inspection without Cloud credentials.
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 'without Cloud credentials' and refers to local paths, indicating this tool is for offline inspection. It does not explicitly contrast with alternatives but the context from siblings and the clear scope imply 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.
Create/update a project auth user and send a trusted invite magic link. Requires service_key and an allowed redirect_url.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address of the auth user to invite | ||
| is_admin | No | Set project_admin status before sending the invite | |
| project_id | Yes | The project ID | |
| client_state | No | Optional opaque state preserved through invite verification | |
| redirect_url | Yes | Allowed auth redirect URL for the invite link |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool creates/updates and sends an invite requiring service_key and redirect_url. However, it omits details about return values, side effects, or what happens on update vs create. The mention of 'service_key' not present in the schema also causes confusion.
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 very concise, consisting of two short sentences. It front-loads the main action. However, it could benefit from a slightly more structured format to separate the action from requirements.
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 (5 parameters, 3 required) and no output schema, the description should explain what the tool returns or side effects. It only states it sends an invite link but does not specify the return value (e.g., success confirmation, user object). This leaves a significant gap for an AI 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 description coverage is 100%, but the description adds minimal additional meaning. It mentions 'requires service_key' which is not in the schema, contradicting the parameter set. It does clarify that 'redirect_url' must be an allowed one and 'is_admin' sets project_admin status, but overall adds little value and introduces confusion.
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/updates a project auth user and sends a trusted invite magic link. This distinguishes it from siblings like 'create_auth_user' (which likely just creates without invite) and 'request_magic_link' (which is for existing users).
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 mentions required prerequisites ('service_key' and 'allowed redirect_url'), providing basic usage context. However, it does not explicitly state when to use this tool vs alternatives, nor does it provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invoke a deployed function via HTTP. Free functions behave like the direct test path; paid functions require idempotency_key and may spend allowance, returning a result or pollable run_id. Stable errors preserve code and set isError=true.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body (string or JSON object) | |
| name | Yes | Function name to invoke | |
| wait | No | When a paid invocation returns a 202 run handle, poll the run and replay the same idempotency key for the retained result. | |
| method | No | HTTP method (default: POST) | |
| headers | No | Additional headers to send | |
| project_id | Yes | The project ID | |
| timeout_ms | No | Maximum wait time in milliseconds when wait is true. | |
| idempotency_key | No | Stable Idempotency-Key required by paid function invocations. Reuse it for the same paid intent; use a new key only for a new paid intent. | |
| poll_interval_ms | No | Polling interval in milliseconds when wait is true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds valuable behavioral details: paid functions require idempotency_key, may spend allowance, return a result or pollable run_id, and handle stable errors by preserving code with isError=true. 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 concise (3 sentences) and front-loaded with the core action. Every sentence adds essential behavioral context 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?
For a tool with 9 parameters and no output schema, the description covers key behavioral aspects (free vs paid, error handling, polling). It mentions return types (result or run_id) but lacks detail on response structure. Overall, sufficiently 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%, so baseline is 3. The description does not add new meaning to parameters beyond what schema descriptions already provide. It mentions idempotency_key and wait in context, but that is implicit from 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 invokes a deployed function via HTTP, distinguishing free vs paid behavior. While sibling tool names like 'create_function_run' suggest different purposes, the description itself is specific and 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 provides clear guidance on when to use the tool by differentiating free vs paid functions and their requirements (idempotency_key, spending allowance). However, it does not explicitly contrast with similar siblings like 'create_function_run'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a queued or running managed job.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Managed job run ID | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it only states the basic action. It does not mention side effects, reversibility, permissions, or error conditions, which is insufficient for a mutation tool.
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, direct sentence with no extraneous information. It is perfectly concise and front-loaded with the key action.
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 simple mutation tool with 2 parameters and no output schema, the description is adequate but minimal. It lacks context about job state transitions or consequences of cancellation, so it is not fully 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%, so the schema already describes both parameters. The description adds no additional meaning beyond the schema, meeting the baseline but providing no extra value.
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 the action ('Cancel') and the resource ('queued or running managed job'), clearly distinguishing it from sibling tools like jobs_submit or jobs_get.
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 (e.g., jobs_purge, jobs_get) or when not to use it. The description provides no context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a completed managed job's artifact by filename to a local file. Discover the recorded filenames from the artifacts map returned by jobs_get; the legacy run402:// refs were retired in favor of these gateway URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Managed job run ID (must be completed) | |
| filename | Yes | Artifact filename to download. Discover the recorded set from the artifacts map returned by jobs_get. | |
| project_id | Yes | The project ID | |
| output_path | Yes | Local filesystem path to write the artifact bytes to. Parent directories will be created. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the output is written to a local file and that parent directories are created. However, it does not disclose if the file is overwritten, the potential for long downloads, or any side effects beyond writing. Some gaps remain.
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 consists of two tightly-written sentences. The first sentence immediately defines the primary purpose, and the second provides necessary context about prerequisite data and legacy information. No filler or 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?
The description explains the tool's purpose and parameter semantics well, but it does not cover the return value (if any) or error scenarios (e.g., what happens if the file doesn't exist). Given no output schema and no annotations, some completeness is missing, though the core usage is clear.
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%, providing a baseline of 3. The description adds value beyond the schema by specifying that job_id must be from a completed job, that filenames come from jobs_get's artifacts map, and that output_path will create parent directories. This extra context improves parameter understanding.
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 ('download') and the specific resource ('completed managed job's artifact by filename to a local file'). It distinguishes this tool from siblings by mentioning that filenames are discovered via jobs_get, and it notes that legacy refs are retired, providing clear differentiation.
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 context for when to use the tool: after a managed job is completed and after retrieving filenames from jobs_get. It implies the job must be completed (reinforced in parameter description). It does not explicitly list when not to use it, but the guidance is sufficient for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a managed job run by id.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Managed job run ID | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full burden. It only states 'Get', which implies a read operation, but fails to mention permissions, rate limits, or what the response contains. Minimal behavioral insight.
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?
One clear, concise sentence with no extraneous information. Front-loaded and 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?
For a simple retrieval tool with full schema coverage, the description is adequate but minimal. It does not mention that no output schema exists, nor does it clarify the scope of the job run data returned.
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 both parameters described. The description adds no additional meaning beyond the schema, meeting the baseline for high coverage.
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 'Get' and the resource 'managed job run by id', which is specific and distinguishes from sibling tools like 'jobs_cancel', 'jobs_logs', etc.
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 explicit guidance on when to use this tool versus alternatives like 'jobs_logs' or 'jobs_download_artifact'. The description implies usage for retrieving a specific job run, but lacks when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read recent runner logs for a managed job. Use tail to cap entries and since for an ISO-8601 lower bound; legacy epoch milliseconds are still accepted.
| Name | Required | Description | Default |
|---|---|---|---|
| tail | No | Maximum number of log entries to return | |
| since | No | Only include logs at or after this ISO-8601 timestamp. Legacy epoch milliseconds are also accepted. | |
| job_id | Yes | Managed job run ID | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full responsibility. It correctly implies a read-only operation and notes legacy epoch millisecond acceptance, but omits details on auth requirements, rate limits, return format, or log retention. The behavioral traits disclosed are minimal but not misleading.
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, zero wasted words. The purpose is front-loaded, and the parameter guidance is compact yet informative. Every sentence serves a clear 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's simplicity (4 parameters, no output schema), the description provides adequate context for a read-only log retrieval operation. It explains the optional parameters and constraints. However, it does not describe the output format or any limitations like pagination or log retention period, which would enhance completeness.
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 'description' fields already explaining each parameter. The description adds some context by stating 'use tail to cap entries' and 'since for an ISO-8601 lower bound', but this largely echoes the schema. No new parameter semantics beyond what the schema provides.
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 'Read' and the resource 'recent runner logs for a managed job', making the tool's purpose unambiguous. It distinguishes from siblings like 'jobs_get' and 'get_function_logs' by specifying 'runner logs' rather than job metadata or function logs.
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 advises on using optional parameters 'tail' and 'since', but does not provide explicit guidance on when to use this tool versus alternatives (e.g., 'jobs_get' for job status, 'get_function_logs' for function logs). The context is clear but lacks when-not-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purge all managed job runs for a project, terminating known active runners first.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses that active runners are terminated, which is valuable. However, it does not mention irreversibility, required permissions, or potential impacts on other resources. More detail would be beneficial.
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, well-structured sentence. It communicates the core action and a key behavioral detail without any fluff or repetition. Highly 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?
Given the simplicity of the tool (one parameter, no output schema), the description is fairly complete. However, it lacks information about return values, error handling, or any prerequisites. For a destructive action, more context would improve completeness.
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 schema has 100% coverage for the single parameter project_id with a description 'The project ID'. The tool description adds no additional semantic meaning beyond what the schema already provides. 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 uses specific verb 'purge', identifies the resource 'managed job runs', and scopes it to 'for a project'. It also mentions a unique behavioral aspect: 'terminating known active runners first'. This clearly distinguishes it from sibling tools like jobs_cancel or jobs_submit.
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?
While the description implies this tool is for bulk cleanup of job runs, it does not explicitly state when to use this tool over alternatives like jobs_cancel. There is no mention of prerequisites, limitations, or exclusions. The guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a platform-managed job. The request must match the gateway jobs API shape: job_type, input with input.json, and max_cost_usd_micros. The SDK supplies the required idempotency header.
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | Gateway-shaped managed job submit request | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It mentions platform management and idempotency but lacks details on auth needs, destructive potential, or process outcomes.
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 front-loaded sentences with zero waste. Every word serves a purpose, efficiently conveying the tool's function and key requirement.
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 and nested objects, the description adequately covers the request shape but omits expected return value or post-submission 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 coverage is 100%, so baseline is 3. The description reiterates required fields (job_type, input, max_cost_usd_micros) already in schema, adding little extra meaning.
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 'Submit a platform-managed job' with a specific verb and resource. It distinguishes from siblings like jobs_get and jobs_cancel by focusing on submission.
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 clear context on the expected request shape but does not explicitly state when to use this tool versus alternatives or mention exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Link a wallet to an existing email organization, enabling hybrid Stripe + x402 access. Fails if the wallet is already linked elsewhere.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The organization ID (from create_email_organization) | |
| wallet | Yes | The wallet address to link (0x...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It discloses a failure condition and the effect (enabling hybrid access), but does not mention authorization requirements, whether the operation is idempotent, or any other side effects. For a mutation tool, this is adequate but not comprehensive.
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 covering purpose and a key behavioral note (failure condition). No redundant information, front-loaded with the main action.
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 required parameters, no output schema), the description covers the essential purpose and a notable failure case. It does not describe the success return value, but that is generally acceptable for a straightforward mutation.
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 provides full descriptions for both parameters (org_id and wallet), making the schema coverage 100%. The description adds context about the overall purpose but does not add new parameter-specific meanings 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?
Description clearly states the action (link wallet to organization), the resource (existing email organization), and the outcome (enabling hybrid Stripe + x402 access). It distinguishes from siblings by specifying the linkage operation, which no other sibling tool explicitly performs.
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?
Description provides clear context that the organization must already exist (implied by 'existing email organization'), and mentions a failure condition (wallet already linked elsewhere). However, it does not explicitly state when NOT to use this tool or suggest alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sent emails from the project's mailbox. Shows message ID, template, recipient, status, and timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Pagination cursor (message id from prior page) | |
| limit | No | Max messages to return (server caps at 200) | |
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| direction | No | Filter to received (inbound) or sent (outbound) messages. Omit for both. 'inbound' is the reconciliation backstop for a missed reply_received webhook. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. The description claims 'list sent emails' but the direction parameter can filter inbound or outbound, making the statement misleading. It fails to mention that results are paginated, ordered, or how the API handles limits. This inaccuracy reduces trust and 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 concise at two sentences but lacks structure (e.g., no bullet points or clear separation of purpose from fields). It is not overly verbose, but the misleading 'sent emails' phrase costs efficiency. Could be slightly improved without adding 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 5 parameters, no output schema, and no annotations, the description is incomplete. It does not explain pagination behavior (after cursor, limit), default direction, or how to handle the mailbox parameter when the project has one mailbox. The return format is only hinted ('Shows message ID, template...') without details on order or structure. More context is needed for reliable agent usage.
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 100% description coverage, so the parameters are already well-documented. The tool description does not add any additional meaning or context about the parameters beyond what the schema provides. According to guidelines, baseline 3 is appropriate when schema coverage is high.
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 emails from a mailbox and enumerates returned fields (message ID, template, recipient, status, timestamp). It implicitly distinguishes from sibling tools like get_email (single email) and send_email. However, it inaccurately specifies 'sent emails' when the direction parameter allows both inbound and outbound, which slightly undermines clarity.
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 (e.g., get_email for individual messages, list_mailboxes for mailbox metadata). Missing context on pagination (after cursor, limit), default behavior, or filtering with the direction parameter. The description does not help the agent decide when to include or omit optional parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List durable runs for a function, filterable by status, event_type, time window, limit, and cursor.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Function name | |
| limit | No | Maximum runs to return (max 100). | |
| since | No | Only include runs created/updated at or after this ISO timestamp or epoch ms. | |
| until | No | Only include runs created/updated before this ISO timestamp or epoch ms. | |
| cursor | No | Pagination cursor returned by a prior list call. | |
| status | No | Filter by run status | |
| event_type | No | Filter by event type | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states the basic action and filters, without disclosing behavioral traits like read-only nature, pagination behavior, ordering, or rate limits. This is minimal for a list tool.
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, clear sentence that front-loads the main action and key features. There is 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?
No output schema or annotations exist, yet the description does not explain return format, pagination details, or default behavior. For a list tool, this leaves significant gaps in completeness.
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 adds minimal extra meaning (e.g., 'durable runs'), but mostly repeats filterable aspects already in schema. It does not provide additional semantic context beyond what is available.
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 'list' and the resource 'durable runs for a function', and lists filterable parameters. It distinguishes from sibling tools like 'get_function_run' (single run) and 'list_functions' (functions, not runs).
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 when to use (to list runs for a function) and specifies filter options. However, it does not explicitly exclude cases or contrast with other tools, but the context is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all deployed functions for a project. Shows names, URLs, Node runtime, timeout, memory, resolved direct deps, and injected @run402/functions compatibility metadata: deployed runtime_version, gateway runtime_current_version, guaranteed runtime_minimum_version, and runtime_stale. Rebuild stale functions with functions_rebuild; an unchanged-source redeploy does not refresh the injected runtime.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavior. It details the fields returned and notes the rebuild requirement for runtime updates, giving good insight into the tool's output and side-effect knowledge.
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 sentences: first states action and output fields, second provides actionable guidance. No fluff, front-loaded with 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?
Despite no output schema, the description enumerates all returned fields and includes critical context about runtime staleness and rebuild action, making the tool fully understandable 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?
The single parameter `project_id` is fully described in the schema (100% coverage). The description does not add extra semantic meaning beyond stating the project context, so baseline score 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 'List all deployed functions for a project', specifying the action and resource. It lists the fields included, distinguishing it from other list tools like deploy_list or list_runs.
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 clear guidance on what to do after listing (rebuild stale functions) and notes that an unchanged-source redeploy does not refresh runtime. Lacks explicit when-not-to-use but offers context for the rebuild action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pending project transfers OFFERED TO the authenticated wallet (v1.59+). Each entry carries preview_path for deep-linking into the preview tool. Calls GET /agent/v1/transfers/incoming.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Opaque pagination cursor (next_cursor from a prior page). | |
| limit | No | Page size (default 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description discloses the GET HTTP method, the API endpoint, and the fact that entries include a preview_path for deep-linking. It also mentions the version requirement. It does not explicitly state that the operation is read-only, but the nature of listing transfers implies it. Overall, it provides sufficient behavioral context for a list tool.
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 covering purpose, scope, version, preview_path, and the HTTP endpoint. Every sentence adds value, with no redundancy or 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?
While the description covers the main purpose and pagination parameters, it lacks details about the return structure beyond the preview_path field. Since no output schema is provided, the description should describe what fields to expect in each entry. This omission leaves the agent uncertain about the response format, making the context incomplete for a well-informed invocation.
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 (after, limit) are fully described in the input schema, achieving 100% schema description coverage. The description does not add any new meaning or usage guidance beyond what the schema already provides, so it meets the baseline without additional value.
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 specifies the action ('List pending project transfers'), the scope ('OFFERED TO the authenticated wallet'), and distinguishes from siblings like list_outgoing_transfers by emphasizing 'incoming'. It also adds version info and the API endpoint, leaving no ambiguity.
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 clear context for when to use the tool (to view incoming transfers) but does not explicitly state when not to use it or suggest alternatives like list_outgoing_transfers or preview_project_transfer. The purpose is understandable, but usage guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List a project's mailboxes, including address/managed_address, default-role metadata (is_default_outbound, is_auth_sender), readiness (can_send, can_receive, send_blocked_reason, domain_kind), footer-policy fields, mailbox_settings, and next_actions. Use before choosing or repairing email defaults.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether the tool is read-only, authorization requirements, or rate limits. It only describes the output fields.
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, consisting of two sentences: one stating the purpose and output fields, and another providing usage guidance. 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?
The description covers the return fields and usage context. For a simple list tool with one parameter and no output schema, it is fairly complete, though it lacks mention of pagination or limits.
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 fully describes the sole parameter 'project_id' with 100% coverage. The description adds no additional meaning beyond what the schema already provides.
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 'List' and the resource 'mailboxes' for a project. It enumerates specific fields returned, distinguishing it from sibling tools like 'get_mailbox' which retrieves a single mailbox.
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 'before choosing or repairing email defaults', providing a context. However, it does not explicitly state when not to use it or mention alternatives like 'get_mailbox' for singular retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List durable webhook delivery rows for the project's mailbox. Webhook delivery is at-least-once with bounded retries + backoff; failures land in 'failed_permanent' (the dead-letter queue). Filter by status to inspect what was lost. Consumers must dedupe on the envelope idempotency_key.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Pagination cursor (delivery id from a prior page) | |
| limit | No | Max rows to return (server caps at 200) | |
| status | No | Filter by delivery status. 'failed_permanent' is the dead-letter queue (events that exhausted retries or failed permanently). | |
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses at-least-once delivery, retries, backoff, and the dead-letter queue concept. However, it omits pagination behavior, rate limits, auth requirements, and whether the operation is read-only.
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 (3 sentences), front-loaded with the purpose, and each sentence adds value without redundancy. It efficiently covers the core concept and critical instructions.
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 (5 params, no output schema, no annotations), the description covers essential behavioral aspects but lacks details on output shape (e.g., fields beyond idempotency_key), pagination usage of 'after', and the 'limit' parameter cap. It is adequate but not fully 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 description coverage is 100%, so the baseline is 3. The description adds value by mentioning the need to dedupe on idempotency_key and to filter by status, but does not significantly enhance understanding of individual parameters 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 it lists webhook delivery rows for the project's mailbox, using a specific verb and resource. It distinguishes from sibling tools like list_mailbox_webhooks and includes behavioral context (durable, at-least-once retries, dead-letter queue).
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 this tool to inspect lost events by filtering on status, but it does not explicitly state when to use versus alternatives (e.g., redrive_mailbox_webhook_delivery). No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all webhooks registered on the project's mailbox.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but discloses no behavioral traits beyond 'list all'. No mention of pagination, ordering, or read-only nature.
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 redundancy, front-loaded with action and resource. Highly concise.
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?
Adequate for a simple list operation, but lacks details about response content (e.g., webhook properties) and the optional mailbox parameter usage. No output schema to fill gaps.
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 describes parameters. Description adds no extra meaning beyond restating the resource context.
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 specifies action (list), resource (webhooks), and scope (on the project's mailbox), distinguishing it from siblings like list_mailboxes and list_mailbox_webhook_deliveries.
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 explicit guidance on when to use this tool versus alternatives like list_mailbox_webhook_deliveries or filtering options. Usage is implied by the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every notification channel for the operator: email, webhook, and every live (non-revoked) Telegram binding with its id, status (pending/active/revoked), chat metadata, and label. Use this to find a telegram_binding_id for create_notification_rule.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains what channels are listed (email, webhook, live Telegram bindings) and details about Telegram bindings. It notes that revoked bindings are excluded. No mention of pagination or rate limits, but the behavior is transparent enough for a read-only list operation.
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 lists what the tool does and the output, second gives a usage example. No filler words, 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?
No output schema exists, so the description must explain return values. It details Telegram binding fields but omits structure for email and webhook channels. Still relatively complete for a 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?
The input schema has zero parameters, so the baseline is 4. The description adds value by explaining the output fields, which compensates for the lack of 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 verb 'list' and resource 'notification channels', specifying types (email, webhook, live Telegram bindings) and output fields (id, status, metadata, label). This distinguishes it from sibling tools like list_notification_rules and create_notification_rule.
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 'Use this to find a telegram_binding_id for create_notification_rule,' providing a concrete use case. It implies when to use this tool but does not explicitly state alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the operator's Telegram routing rules. Each rule ANDs its match dimensions (project_id, source, event_types, classes); an omitted dimension is a wildcard. One rule always targets exactly one Telegram binding.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description explains the rule matching behavior (wildcards, AND logic) and that each rule targets one binding. It does not disclose aspects like pagination, ordering, or read-only nature, but for a simple list operation, it provides adequate 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?
Two terse sentences: the first front-loads the action, the second explains the rule semantics. No redundancy, 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?
Despite no output schema and zero parameters, the description explains the core concept of routing rules sufficiently for an agent to understand the tool's purpose and behavior. Minor gaps like pagination or sorting details are not critical for a basic list.
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?
There are zero parameters, so baseline is 4. The description adds context about what is listed (routing rules with specific dimensions) beyond the empty schema, giving meaning to the output.
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 'Telegram routing rules,' using a specific verb and resource. It further explains the structure of each rule (ANDing dimensions, wildcards, target binding), making it distinct from siblings like list_notifications or list_notification_channels.
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 clarifies that the tool lists routing rules, implying its use for retrieving these rules. However, it does not explicitly state when to use this tool over siblings (e.g., list_notifications) or provide exclusions. The context is clear but lacks definitive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the operator's notification audit log (delivered, failed, and skipped attempts). Paginated; filter by event type or since timestamp.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by event_type (e.g. project_past_due) | |
| after | No | Opaque pagination cursor (next_cursor from a prior page). | |
| limit | No | Page size (default 50, max 200) | |
| since | No | ISO timestamp; only notifications at or after this time |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It reveals that the tool returns delivered, failed, and skipped attempts and supports pagination and filtering. However, it does not explicitly state that the operation is read-only, mention rate limits, or describe the response format. The addition of the audit log context provides moderate value beyond the schema.
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, well-structured sentence that efficiently conveys the tool's purpose and key features (audit log, status types, pagination, filters). No superfluous words or 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 lack of an output schema and annotations, the description provides the core purpose and capabilities but omits details about the response structure, error handling, or any side effects. For a data retrieval tool with four parameters, the description is minimally adequate but leaves important context unspecified.
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 all four parameters having descriptions. The description's mention of filtering by event type or since timestamp mirrors the parameter descriptions without adding new semantic details. Thus, the description does not significantly enhance understanding 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 lists the operator's notification audit log, specifying three types of attempts (delivered, failed, skipped). This distinguishes it from sibling tools like get_notification_preferences (which retrieves preferences) and test_notification (which sends a test).
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 no guidance on when to use this tool versus alternatives. It mentions pagination and filtering capabilities but does not address scenarios where a different tool (e.g., get_notification_preferences) would be more appropriate. Given the large set of sibling tools, explicit usage guidelines are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the members of an org and their roles. Params: org_id.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The org id, e.g. `org_...`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits like read-only nature, rate limits, or authorization needs. It only states the action without additional 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?
Extremely concise with one sentence plus a brief param note. No unnecessary words, and important information 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?
While the tool is simple, the description does not explain return structure, pagination, or role details. With no output schema, additional context would be beneficial for completeness.
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 provides full coverage for the single parameter (org_id). The description redundantly mentions 'Params: `org_id`' but adds no new 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 clearly states the verb 'list' and the resource 'members of an org and their roles', distinguishing it from sibling tools like 'list_orgs' and 'get_org'.
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 vs alternatives such as 'add_org_member' or 'set_org_member_role'. The description lacks context about prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the orgs you are a member of, with each org's id, display name, your role, and membership status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral burden. It describes output fields but lacks details on pagination, ordering, or whether it includes all membership statuses. However, for a simple list tool, basic transparency is provided.
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, clear and direct, no unnecessary words. Front-loaded with key 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?
For a simple no-param tool, the description specifies returned fields. Missing details like authentication requirements or pagination, but overall adequate given simplicity.
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?
No parameters exist (empty schema, 100% coverage). The description adds no param info, which is acceptable. Baseline for 0 parameters is 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 explicitly states it lists orgs the user is a member of and specifies returned fields (id, display name, role, membership status). It clearly distinguishes from siblings like 'get_org' (single org) and 'list_org_members' (org members).
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 when needing a list of user's orgs, but does not explicitly state when to use vs. alternatives or provide exclusions. No guidance on when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pending project transfers INITIATED BY the authenticated wallet (v1.59+). Each entry carries preview_path for deep-linking into the preview tool. Calls GET /agent/v1/transfers/outgoing.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Opaque pagination cursor (next_cursor from a prior page). | |
| limit | No | Page size (default 50). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It specifies the HTTP GET method and mentions the preview_path for deep-linking, implying a read-only operation. However, it does not explicitly state that no mutations occur, nor does it disclose any side effects or authentication requirements beyond the implicit wallet 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?
Two sentences with clear front-loading: first sentence conveys core purpose, second adds a key detail (preview_path) and the API call. No redundancy or unnecessary text.
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 specifies the returned data includes preview_path, but lacks details about the full response structure or pagination behaviour. Given the tool's simplicity and the presence of pagination parameters, a brief note on how to iterate pages would improve completeness. Still, it covers essential context for an agent to begin using the 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% (two parameters: after and limit). The description does not add meaning beyond the schema; the schema already describes 'after' as an opaque cursor and 'limit' as page size with default 50. The description's mention of preview_path is unrelated to parameters, so no additional semantic value.
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 pending project transfers initiated by the authenticated wallet, distinguishing it from incoming transfers and other transfer-related siblings like list_incoming_transfers, initiate_project_transfer, etc. It also mentions the API endpoint and the preview_path field.
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 outgoing initiated transfers, but lacks explicit guidance on when to use this tool versus alternatives such as list_incoming_transfers, preview_project_transfer, or accept_project_transfer. Context from sibling names fills the gap, but the description itself does not provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the authenticated user's active passkeys.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID | |
| access_token | Yes | Authenticated user's access_token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It implies a read operation by using 'List', but does not disclose that it is non-destructive, what authentication is needed beyond the access token, or any other behavioral traits.
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?
One sentence, front-loaded with the verb, no redundant or extra words. It is highly concise and structured effectively.
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 list operation with no output schema, the description should hint at the return format (e.g., list of passkey objects). It does not describe what 'active passkeys' means or the structure of the output, leaving the agent with incomplete information.
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 add any additional meaning beyond the parameter names and descriptions already present 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 the verb 'List' and the resource 'the authenticated user's active passkeys', which is specific and distinguishes it from sibling tools like delete_passkey or passkey_register_options.
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 like delete_passkey or passkey_register_verify. The description only states what it does, not the context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active contained branch projects for a parent project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Parent project ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source for behavioral traits. It does not disclose pagination, result limit, what 'active' means, or any side effects. Merely states the action without depth.
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 that is front-loaded with the action. Every word contributes meaning, 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?
For a list tool with no output schema and no annotations, the description should clarify response format, pagination, and ambiguity of 'active' and 'contained'. It falls short, leaving critical gaps.
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 for project_id. The tool description adds no new meaning beyond what the schema already provides, so 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?
Clearly states the verb 'list' and the specific resource 'active contained branch projects for a parent project'. Distinguishes from siblings like create_project_branch and delete_project_branch by focusing on listing active contained branches.
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 no guidance on when to use this tool versus alternatives like list_projects or other list tools. No prerequisites, conditions, or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Catch up on what happened to a project since you last looked: the durable, cursored feed of deploy activations, mailbox suspensions, transfers, lifecycle cliffs, and verification outcomes, each with platform-suggested next_actions. The feed also carries app-emitted business facts (a deployed function's own events.emit calls) alongside the platform's own events — pass source:"app" to read just the app's facts, source:"platform" for just the platform's operational record, or event_type (comma-separated) to filter to one-or-more specific types; key on (source, event_type) together since app-chosen type names are free-form. Reach for this after any deploy (the apply/promote response hands you a positioned cursor) and at the start of a session on an existing project. Store the returned cursor and pass it back next time; an expired cursor returns reset:true + earliest_cursor instead of an error. Read-only; works even on frozen projects.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size (default 50, max 200). | |
| cursor | No | Opaque cursor from a prior page (the response's `cursor`, or any event's `id`). Returns events strictly after it. Omit on first contact to start from the earliest retained event. Never parse cursors. | |
| org_id | No | Read the org-wide feed instead (union across the org's projects; requires an active org membership). | |
| source | No | Restrict to one source: "app" (business facts a deployed function emitted itself via events.emit) or "platform" (every non-app source — the platform's own operational record). Omit to read both lanes in one merged, cursor-ordered feed. | |
| event_type | No | Restrict to one or more event types, comma-separated (e.g. "signature_completed,booking_created"). Composes with source — e.g. source: "app" + event_type to watch for one specific business fact. | |
| project_id | No | Project whose feed to read. Omit when passing org_id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully carries the burden. It discloses read-only behavior, cursor management (expired cursor returns reset:true + earliest_cursor), composable filtering (source, event_type), and that the feed includes both platform events and app-emitted business facts.
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 paragraph that flows logically from purpose to usage details. While it is somewhat long, every sentence adds value and does not waste words. It is appropriately sized for a complex tool with multiple filtering options and behavioral nuances.
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 lack of an output schema, the description explains cursor behavior, read-only nature, and filtering composition well. However, it does not explicitly describe the response format (fields in each event) or the exact structure of next_actions, which would be helpful for full completeness.
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 good parameter descriptions, but the description adds significant context: explaining cursor storage and passing, combining source and event_type filters, and the meaning of org_id for org-wide feed. This goes beyond what the schema provides.
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 provides a durable, cursored feed of project events (deploy activations, mailbox suspensions, etc.), with filtering by source and event_type. It distinguishes itself from sibling event tools by emphasizing the cursored and durable nature and the inclusion of app-emitted business facts.
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 using the tool after deploys and at the start of a session on an existing project, and notes it works on frozen projects. However, it does not explicitly state when not to use it or mention alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List projects from the named, domain-aware inventory (GET /projects/v1). Membership-scoped by default: every project owned by an org the agent's wallet is an active member of, with name, site_url, custom_domains, org (org_id), and status. SIWX wallet auth is signed automatically. Pass org_id to filter to one org (authorize-before-reveal: non-member/guessed → 403, non-UUID → 400), all:true to read the cross-wallet inventory across every wallet controlling your operator email, or limit/cursor to paginate.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Read the cross-wallet inventory across every wallet controlling your operator email instead of just this wallet's membership-scoped slice. Mutually exclusive with org_id. | |
| limit | No | Page size for the membership-scoped read (server default 50, max 200). | |
| cursor | No | Pagination cursor from a previous response's next_cursor. | |
| org_id | No | Optional org (organization) id to filter to. Authorize-before-reveal: a non-member or guessed id returns the same 403 as a real-but-unauthorized org; a non-UUID id is a 400. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: authentication via SIWX wallet, error responses for org_id (403/400), pagination with limit/cursor, and the all parameter for cross-wallet inventory. However, it does not explicitly state that it is read-only or mention rate limits, but given no annotations, this is sufficient.
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 paragraph that front-loads the main purpose and provides necessary details. It is relatively concise, though it could be slightly more structured (e.g., bullet points) without losing information. Every sentence contributes 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 no output schema, the description lists returned fields (name, site_url, etc.), explains auth, error cases, and pagination. It covers the main usage scenarios and constraints, making it fairly complete for a listing tool with moderate 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%, so baseline is 3. The description adds minimal meaning beyond the schema's parameter descriptions; it mostly repeats the same information (e.g., org_id authorize-before-reveal, all parameter). No significant extra context is provided.
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 'List projects' and specifies the scope (membership-scoped) and the endpoint. It distinguishes from siblings like project_get by focusing on listing multiple projects, with explicit details on returned fields.
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 when to use this tool for listing projects, but does not explicitly mention when not to use it or provide alternatives such as project_get for single project retrieval. It gives context on filtering and pagination but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List project data snapshots with optional kind filter and keyset pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional snapshot kind filter. | |
| after | No | Keyset pagination cursor from a previous response. | |
| limit | No | Page size, max 100. | |
| project_id | Yes | Project ID whose snapshots should be listed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions optional filtering and pagination, but does not specify ordering, default page size, or confirm that the operation is read-only. The schema provides parameter details, but behavioral traits like side effects are missing.
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, well-structured sentence that front-loads key information. No redundant or unnecessary text.
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 4 parameters and no output schema, the description covers the basic functionality but lacks details on pagination mechanics, default behavior, and ordering. It is adequate but not 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 description coverage is 100%, providing full parameter documentation. The description adds minimal value beyond the schema by reiterating 'optional kind filter and keyset pagination'. Baseline 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 the action ('List'), the resource ('project data snapshots'), and key features ('optional kind filter and keyset pagination'). This distinguishes it from sibling tools like 'create_project_snapshot' or 'get_project_snapshot'.
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?
Usage is implied ('list snapshots'), but there is no explicit guidance on when to use this tool versus alternatives (e.g., 'get_project_snapshot' for a single snapshot). No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List secret keys for a project. Values and value-derived hashes are never shown; use this only to check which keys are configured.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It only states that values and hashes are never shown, but omits other important behaviors such as output format, pagination, error handling, or authorization requirements.
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, consisting of two sentences with no unnecessary words. The purpose is front-loaded, and 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?
The description covers the basic purpose and a key behavioral constraint, but lacks details about the output structure, potential errors, or pagination. For a simple list tool, it is adequate but has clear gaps.
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 already provides 100% coverage with a description for the single parameter 'project_id'. The description does not add any additional semantic information beyond what is 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 'List secret keys for a project' with a specific verb and resource, and differentiates from sibling tools like set_secret and delete_secret by noting that values and hashes are never shown.
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 'use this only to check which keys are configured', providing clear context for when to use the tool. However, it does not mention when not to use it or provide alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all KMS signers owned by the project, including deleted ones.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the inclusion of deleted signers, which is a behavioral trait. However, it does not mention permissions, rate limits, or return format, leaving gaps in 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 a single sentence with no waste. It is front-loaded with the main action. While concise, it could benefit from a brief mention of the return type without losing efficiency.
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 simple list tool with one parameter and no output schema, the description covers the basic purpose and scope. However, it lacks details about the output (e.g., what properties are returned) and any pagination or ordering, which a complete description should include.
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' described in schema. The description adds no additional parameter information beyond restating 'owned by the project', so it provides no extra value over 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 action 'List' and the resource 'KMS signers', specifies scope 'owned by the project, including deleted ones', and distinguishes it from sibling tools like get_signer (specific signer) and delete_signer.
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?
While not explicit, the description implies when to use this tool (listing all signers, including deleted) versus siblings like get_signer (single signer) or delete_signer (deletion). The inclusion of 'including deleted ones' subtly guides against using it when only active signers are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all subdomains claimed by a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the description indicates a safe read operation, it lacks details on pagination, limits, or what 'claimed' means relative to sibling tools. No annotations are provided.
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, clear sentence with no unnecessary words, making it easy to parse.
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?
With no output schema, the description omits what the response contains (list of strings? objects?), and lacks context on how this tool relates to claim_subdomain and delete_subdomain.
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 single parameter (project_id) has full schema coverage, and the description adds no additional meaning beyond the schema's 'The project ID'.
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 (list), resource (subdomains), and scope (claimed by a project), distinguishing it from sibling tools like list_custom_domains.
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 no guidance on when to use this tool versus alternatives such as list_custom_domains or claim_subdomain, and no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List redacted tenant x402 payment records for priced function web routes on a project (GET /projects/v1/:project_id/tenant-payments). Requires project.tenant_payments.read: org developer+ or read-scoped project grant/delegate. Raw X-PAYMENT headers, authorization hashes, and internal metadata are never returned.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Opaque keyset cursor from a previous next_cursor. | |
| limit | No | Page size. Server default 50, max 200. | |
| status | No | Optional status filter. | |
| project_id | Yes | Project id, e.g. `prj_...`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that 'Raw X-PAYMENT headers, authorization hashes, and internal metadata are never returned', which is useful behavioral info. However, it lacks details on pagination behavior, response structure, or side effects, leaving gaps.
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 very concise, consisting of three short sentences that front-load the purpose. Every sentence adds unique value: action, permission, and data exclusions. No unnecessary 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?
The description covers the core purpose and permission but lacks critical context like output format (no output schema exists) and pagination details (despite the 'after' parameter implying cursor-based pagination). Given 4 parameters and no output schema, it is moderately incomplete.
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 adds no additional meaning to the parameters (after, limit, status, project_id) beyond what the schema already provides.
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 'redacted tenant x402 payment records for priced function web routes on a project', specifying the exact verb, resource, and scope. It also provides the HTTP endpoint, which helps differentiate from billing_history or other payment-related 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 provides clear context for when to use the tool (for tenant payments on a project) and includes the required permission. However, it does not explicitly state when not to use it or mention alternative tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List published versions of a project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits such as read-only nature, pagination, sorting, or effects on the system. The agent is left unaware of whether this operation is safe or has 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 a single concise sentence with no wasted words. It is 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?
For a simple list tool with one parameter and no output schema, the description is minimal but does not cover expected response format, potential pagination, or ordering. It is adequate but leaves gaps 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% for the single parameter 'project_id', which is adequately described in the schema. The description does not add any additional meaning beyond the schema, so 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 'List published versions of a project' clearly states the action (list) and the resource (published versions) with a specific scope (of a project). It distinguishes itself from sibling tools like 'delete_version' and 'update_version' by focusing on listing.
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 is provided on when to use this tool versus alternatives (e.g., 'list_projects' or other list operations). The description lacks context on prerequisites, such as requiring a project ID, and does not indicate 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.
Create WebAuthn passkey login options for a project app origin.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Optional email hint. Does not expose allowCredentials. | ||
| app_origin | Yes | Exact app origin for the WebAuthn ceremony | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits (e.g., that this generates options without side effects, or requires user interaction). It only states the action without explaining the result or implications for the agent.
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, front-loaded with key information. No redundant or extraneous content.
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 and no annotations, the description is minimal. It covers the basic purpose but lacks details on what the tool returns or any prerequisites, making it adequate but not comprehensive.
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?
All three parameters are described in the schema (100% coverage), so the description adds no new meaning beyond 'create for a project app origin'. Baseline 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 the action ('Create') and the resource ('WebAuthn passkey login options') with specific scope ('for a project app origin'). It distinguishes from sibling tools like 'passkey_register_options' by specifying 'login'.
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 explicit guidance on when to use this tool vs alternatives like 'passkey_register_options' or 'passkey_login_verify'. Usage is implied by the name and description, but no direct instructions or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a browser WebAuthn assertion and return a normal Run402 auth session.
| Name | Required | Description | Default |
|---|---|---|---|
| response | No | PublicKeyCredential assertion response JSON from the browser | |
| project_id | Yes | The project ID | |
| challenge_id | Yes | challenge_id returned by passkey_login_options |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks disclosure of prerequisites, side effects, error conditions, or security implications. Does not mention that it likely requires a prior challenge or that it creates a session.
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, front-loaded sentence with 13 words. No redundant information or extraneous details.
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 has low complexity with 3 well-described parameters and no output schema. Description covers the essential purpose, though additional context about the prerequisite challenge_id could be helpful.
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. Description adds no extra meaning beyond the schema, such as format or constraints for the 'response' parameter.
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 verb (verify), resource (WebAuthn assertion), and outcome (return auth session). Distinguishes from siblings like passkey_register_verify and passkey_login_options.
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 explicit when-to-use or when-not-to-use guidance. Implies usage in login flow after passkey_login_options, but no alternatives or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create WebAuthn passkey registration options for the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
| app_origin | Yes | Exact app origin for the WebAuthn ceremony | |
| project_id | Yes | The project ID | |
| access_token | Yes | Authenticated user's access_token |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the basic action but does not explain side effects, return value format, or whether it creates a session. Missing behavioral details like idempotency or expiration.
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 wasted words, directly communicates the tool's 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?
Adequate for a simple tool, but lacks mention of return format and the next step (verification with passkey_register_verify). No output schema or annotations to supplement.
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 the context 'for the authenticated user' but does not explain parameter roles 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?
Description clearly states the tool creates WebAuthn passkey registration options for the authenticated user, specifying the verb, resource, and user scope. It distinguishes from sibling tools like passkey_register_verify and passkey_login_options.
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 when to use the tool (for passkey registration) but lacks explicit guidance on when not to use it or comparisons to alternatives like passkey_register_verify or passkey_login_options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a browser WebAuthn registration response and store the user's passkey.
| Name | Required | Description | Default |
|---|---|---|---|
| label | No | Optional passkey label | |
| response | No | PublicKeyCredential registration response JSON from the browser | |
| project_id | Yes | The project ID | |
| access_token | Yes | Authenticated user's access_token | |
| challenge_id | Yes | challenge_id returned by passkey_register_options |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool stores the passkey (write operation), but doesn't elaborate on side effects like permanent storage or authentication requirements.
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, front-loaded, no wasted words. Could benefit from a second sentence for context, but still concise.
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?
No output schema or annotations, and 5 parameters. The minimal description leaves out necessary context like the flow from passkey_register_options and the expected format of the response parameter.
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 no additional meaning beyond the schema's parameter 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 the verb 'verify' and 'store' and the resources 'browser WebAuthn registration response' and 'user's passkey', distinguishing it from siblings like passkey_register_options and passkey_login_verify.
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 explicit guidance on when to use this tool vs alternatives. The description does not mention the prerequisite call to passkey_register_options or that it follows the browser registration step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call an arbitrary HTTP(S) URL and automatically satisfy a supported x402 exact-payment challenge. Defaults to a $0.10 ceiling, uses the configured allowance wallet, forwards Idempotency-Key, and returns the HTTP response plus a structured payment receipt.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The HTTP(S) URL to call | |
| body | No | Request body as text or a JSON object | |
| method | No | HTTP method (default: GET) | |
| max_usd_micros | No | Maximum payment in USD micros (default: 100000, or $0.10) | |
| idempotency_key | No | Stable Idempotency-Key forwarded to the seller; on Run402 pending, retry the identical call with the same payer and key | |
| require_receipt | No | Require a verified wallet-rooted merchant offer before payment and a matching receipt after settlement |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show openWorldHint=true and readOnlyHint=false. The description adds that it deducts from the allowance wallet, forwards Idempotency-Key, and returns a receipt. However, it omits potential side effects such as permanent payments or failure modes. With annotations covering the core non-read-only nature, the description adds moderate value.
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, minimal fluff. Every phrase carries meaning: the payment challenge handling, defaults, wallet, idempotency, and return content. 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 6 parameters, no output schema, and openWorldHint, the description covers the payment flow, default ceiling, and return structure. Missing details about error handling (e.g., insufficient balance, unsupported URLs) but still provides a solid operational overview.
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 reinforces defaults (max_usd_micros) and connects idempotency_key to retry semantics. This adds some context beyond the schema but does not introduce new parameter meaning.
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 calls an arbitrary HTTP(S) URL and automatically satisfies x402 payment challenges. This distinct verb+resource combination sets it apart from siblings like list_secrets or contract_call.
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 the tool is for paying HTTP endpoints that use x402. It mentions defaults and forwarding behavior but does not explicitly contrast with other tools or specify when not to use it. Still, the context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the preview document for a project transfer of any pending kind (v1.93+). Returns the safe review payload: project name, custom domains, subdomains, function names, secret NAMES (values are never returned), CI bindings that will be revoked at completion, mailbox summary, billing implications, and — on email transfers — the retain_collaborator offer. Caller must be a party to the transfer. Calls GET /agent/v1/transfers/:transfer_id.
| Name | Required | Description | Default |
|---|---|---|---|
| transfer_id | Yes | Transfer id to preview. You must be a party to it (wallet signer, the addressed-email principal, or an offering-org member). Kind-agnostic — works for wallet and email transfers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description fully carries the burden. It discloses what the return payload contains (including sensitive data like secret names but not values) and the authentication requirement. It does not mention rate limits or side effects, but for a read-only preview this is sufficient.
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, but the first sentence is long and lists many return fields. It is still readable and front-loaded with the core action. Could be slightly more concise, but not wasteful.
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 single parameter, no output schema, and no annotations, the description provides a thorough list of return fields, version requirement, and caller prerequisite. It is nearly complete for guiding an agent, though error conditions could be added.
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 single parameter transfer_id already has a detailed description in the input schema (100% coverage). The main description adds nothing beyond the schema, so it meets the baseline for high coverage.
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 'Fetch' and the resource 'preview document for a project transfer', distinguishing it from sibling transfer tools like accept_project_transfer or initiate_project_transfer. It also mentions the API endpoint for precise identification.
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 specifies that the caller must be a party to the transfer and that the tool is kind-agnostic (works for wallet and email transfers). Although it does not explicitly contrast with siblings, the context makes it clear this is a preview step before acting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authoritative server read of a project — name, owning org, tier, effective status, active deploy, mailbox addresses, and usage vs. tier limits. Live API call; returns no keys (use project_key_cache_status/export for local cached keys).
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID to read (authoritative server view; no keys) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It clearly indicates this is a read operation ('read') and a live API call, implying no destructive side effects. It doesn't detail error handling or rate limits, but for a simple read tool this is adequate.
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 long. The first sentence introduces purpose and key data points, the second clarifies the live nature and key exclusion. 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 simple tool (1 param, no output schema), the description covers what it does, what it returns, and differentiation from siblings. It lacks details on return format or errors, but overall sufficient.
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 already covers 100% of parameters (project_id with description). The description adds minimal extra meaning beyond restating that it's an authoritative server view and no keys. 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's an 'Authoritative server read of a project' and lists specific data returned (name, org, tier, status, deploy, mailbox, usage). It distinguishes from sibling tools by explicitly noting it returns no keys and directing to project_key_cache_status/export for cached keys.
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 context ('Live API call') and directs users to alternative tools for cached keys. While it doesn't explicitly state when not to use this tool, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Export local cached anon/service keys for one project. Requires reveal:true and emits secret material; use only when a credential-required operation needs keys.
| Name | Required | Description | Default |
|---|---|---|---|
| reveal | Yes | Must be true to emit secret key material | |
| project_id | Yes | Project ID to export from the local project-key credential cache |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It states that it emits secret material and requires reveal:true, which is critical. However, it does not mention whether the operation is destructive, if permissions are needed, or the effect on the local cache. More details would improve 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?
Single sentence, front-loaded with purpose, followed by constraints and usage context. Every part is necessary, 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?
Despite no output schema, the description covers the tool's purpose, critical parameter constraint, and appropriate usage context. It lacks details on post-export cache state or security considerations, but is adequate for a simple export 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 value by explicitly stating that reveal must be true and that it triggers emission of secret material, reinforcing and expanding on the schema's 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 verb 'Export' and the resource 'local cached anon/service keys for one project'. It distinguishes from the sibling 'project_key_cache_status' which likely reports status, but does not explicitly name the alternative.
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 explicit condition 'Requires reveal:true' and context 'use only when a credential-required operation needs keys'. This guides the agent to use it only in specific scenarios, but does not list alternative tools for other cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read redacted local project-key cache status for one project. Local cache only; not authoritative project inventory and never returns full keys.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID to inspect in the local project-key credential cache |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adequately discloses that this is a read-only operation on local cache, returns redacted data, and never returns full keys. It does not discuss side effects or rate limits, but the core behavioral traits are covered.
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 with no extraneous information. It is front-loaded with the primary action and quickly specifies limitations.
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 or annotations, the description explains the tool's purpose and limitations but does not describe the return format or data structure. This leaves some ambiguity about what the agent can expect from the response.
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 schema description for the single parameter 'project_id' already explains its purpose. The tool description adds context that it's for the local cache, but adds minimal additional semantic value 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 reads redacted local project-key cache status for one project. It distinguishes itself from authoritative project inventory tools and key export tools by specifying its scope and limitations.
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 indicates when to use this tool by contrasting with authoritative project inventory and full key retrieval. However, it does not explicitly mention alternative tools by name, so the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Server-validate a project and store its id as the active project pointer for this local profile.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID to set as active |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose side effects (e.g., overwriting previous pointer, validation failure behavior, persistence) beyond the basic action. The burden is high without 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 is efficient and front-loaded, containing key action and result. 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 no output schema and minimal description, the tool lacks contextual details about return values, error handling, and side effects, making it incomplete for a simple yet state-changing 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% and description adds no extra meaning beyond the schema's parameter description. 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 clearly states the tool validates a project and sets it as the active pointer, using specific verbs and resource. It distinguishes itself from siblings as no other tool sets the active project pointer.
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?
Usage is implied by the action of setting active project, but no explicit guidance on when to use vs alternatives or prerequisites is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Promote a user to project_admin role by email. Admins can manage secrets from the browser. Requires service_key.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address of the user to promote to project_admin | ||
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does mention the required service_key for authorization, but lacks details on reversibility, idempotency, or what happens if the user already has the role. The extra sentence about admin secrets is tangential.
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, but the second sentence about admin secrets is only tangentially related and adds unnecessary length. The purpose is front-loaded, but the structure could be tighter without the digression.
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 and moderate complexity, the description covers the basic purpose and a required authorization. However, it omits important context such as required preconditions (user must exist in the project), potential errors, and output format. It is adequate but has clear gaps.
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 baseline is 3. The description adds minimal value beyond the schema: it implies the 'email' parameter is the user's email address and that 'project_id' is a project identifier. No additional constraints or formats are given.
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 'Promote a user to project_admin role' with the specific verb 'promote' and resource 'user to project_admin role'. It distinguishes from the sibling tool 'demote_user' which performs the opposite action.
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 mentions a prerequisite 'Requires service_key' but lacks explicit guidance on when to use this tool versus alternatives like 'demote_user' or 'set_org_member_role'. The usage context is implied but not clearly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provision a new Postgres database. Returns project credentials on success, or payment details if x402 payment is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional project name (auto-generated if omitted) | |
| tier | No | Database tier: prototype ($0.10/7d, free with testnet faucet), hobby ($5/30d), team ($20/30d) | prototype |
| org_id | No | Provision into an EXISTING org (v1.82). You must hold a developer+ membership on it. Omit for the cold-start path. Tier is org-governed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses return behavior (credentials on success, payment details if x402 needed), which is helpful. However, it lacks details on destructive nature, authorization requirements, or idempotency, and annotations are absent.
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 short and to the point, but could be slightly expanded to include key contextual details without losing conciseness.
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 (optional parameters, tier options, payment requirement), the description is somewhat incomplete. It does not mention the tier choices or org_id implications, nor does it have an output schema to supplement.
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 documentation coverage is 100%, so the description adds no extra parameter info beyond the schema. No per-parameter elaboration is provided.
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 ('Provision') and the resource ('a new Postgres database'), distinguishing it from sibling tools like 'provision_signer' or project management 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?
No guidance on when to use this tool versus alternatives, such as when to provision a signer or use a different project creation flow. The mention of 'cold-start path' is only in the schema, not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provision an AWS KMS-backed Ethereum signer for signing smart-contract write transactions. Private keys never leave KMS. Cost: $0.04/day rental ($1.20/month) plus $0.000005 per contract call. Requires $1.20 in cash credit at creation (30 days of rent). Non-custodial.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | Yes | Which EVM chain. Cost: $0.04/day rental, requires $1.20 in cash credit at creation. | |
| project_id | Yes | The project ID | |
| recovery_address | No | Optional 0x-prefixed address for auto-drain on day-90 deletion |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: KMS-backed, non-custodial, cost structure, and credit requirement. It does not mention synchronization or completion time, but covers the most important aspects.
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 four sentences, each adding distinct value: purpose, security, cost, requirement. Front-loaded with the main action.
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 (provisioning with costs and security), the description covers essential points. It lacks details about return value or post-creation state, but is otherwise 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%, so parameters are already documented. The description adds context about costs but does not significantly enhance parameter understanding 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 verb 'Provision' and the resource 'AWS KMS-backed Ethereum signer' with its purpose 'for signing smart-contract write transactions'. This distinguishes it from sibling tools like get_signer, delete_signer, etc.
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 clear context including cost and prerequisite ($1.20 cash credit). However, it does not explicitly state when not to use it or mention alternatives like existing signers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish a project as a forkable app. Set visibility and tags for discoverability.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for discoverability (e.g. ['auth', 'rls', 'todo']) | |
| project_id | Yes | The project ID to publish | |
| visibility | No | Visibility: public (listed in browse_apps), unlisted (accessible by ID), private (default) | |
| description | No | App description | |
| fork_allowed | No | Whether other users can fork this app (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description lacks details on side effects, required permissions, or behavioral constraints beyond 'publish' and 'set visibility and tags'.
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 that efficiently conveys the core action and key options. Slightly more detail could be included without harming conciseness.
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 lack of annotations and output schema, the description should cover default values, effect of 'forkable', and what happens post-publish. It does not, leaving gaps for the 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 has 100% coverage of parameter descriptions, so baseline is 3. Description adds context for visibility and tags but does not elaborate on description or fork_allowed 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?
Clearly states the verb 'publish' and resource 'project as a forkable app', distinguishing it from sibling tools like fork_app and browse_apps.
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 explicit guidance on when to use this tool versus alternatives like fork_app or browse_apps. Does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Redrive a failed/cancelled/expired durable function run with an optional retry override and optional wait.
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Wait until the run becomes terminal before returning. | |
| retry | No | ||
| run_id | Yes | Function run id, fnrun_... | |
| project_id | Yes | The project ID | |
| timeout_ms | No | Maximum wait time in milliseconds. | |
| poll_interval_ms | No | Polling interval in milliseconds. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral transparency burden. It does not disclose important traits such as whether redriving creates a new run, replaces the original, or is idempotent. The 'optional wait' parameter is mentioned but not explained in the description.
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 key optional features without extraneous text.
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 tool has 6 parameters and a nested retry object, but no output schema. The description does not explain the return value (e.g., the new run ID or status), nor does it clarify behaviors like what happens when wait is true vs false. This leaves significant gaps for the 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?
The schema description coverage is 83%, so the baseline is 3. The description adds minimal value by listing 'retry override' and 'wait' as options, but these are already apparent from the schema's required/optional fields and property 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 the action ('Redrive') and the specific resource ('failed/cancelled/expired durable function run'), distinguishing it from sibling tools like 'create_function_run' or 'cancel_function_run'.
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 when a run is in a failed/cancelled/expired state, but does not explicitly exclude other states or provide comparisons to alternatives. It gives clear context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-queue a dead-lettered (failed_permanent) webhook delivery so the worker attempts delivery again. Use after fixing the consumer endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID | |
| delivery_id | Yes | The delivery id to re-queue (from list_mailbox_webhook_deliveries) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the worker will attempt delivery again but does not disclose behavior for non-failed deliveries, rate limits, idempotency, or authorization requirements.
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, front-loaded with action and purpose. Every sentence adds value with 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 no annotations and no output schema, the description adequately explains the core action and when to use. However, it lacks details on edge cases (e.g., non-failed delivery, success indication) and does not clarify the optional mailbox parameter.
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 any parameter-specific meaning beyond what the schema already provides (e.g., delivery_id source).
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 (re-queue), resource (dead-lettered webhook delivery), and purpose (worker attempts again). It distinguishes from sibling tools like list_mailbox_webhook_deliveries by specifying the action on failed_permanent deliveries.
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 clear usage context: 'Use after fixing the consumer endpoint.' It implies when to use but does not explicitly state when not to or mention alternatives like checking status first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a webhook on the project's mailbox. Receives POST notifications for email events (delivery, bounced, complained, reply_received).
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Webhook callback URL | |
| events | Yes | Events to subscribe to. Valid: delivery, bounced, complained, reply_received | |
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It does not mention idempotency, side effects (e.g., immediate POST notifications), authentication needed, or whether the webhook secret is returned. The description only states it receives notifications.
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 long, front-loaded with the core purpose, and each sentence adds necessary information. No redundancy or 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 has 4 parameters and no output schema, the description covers the basic purpose and events but lacks information on webhook lifecycle (e.g., how to manage, what happens after registration). It is adequate but not comprehensive.
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 all parameters. The description adds no extra meaning beyond what's in the schema, such as constraints like HTTPS for url or that mailbox can be omitted when only one mailbox exists. 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 'register' and resource 'webhook on mailbox', and lists specific email events (delivery, bounced, complained, reply_received). This distinguishes it from sibling tools like delete_mailbox_webhook.
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 is provided on when to use this tool versus alternatives (e.g., update_mailbox_webhook, list_mailbox_webhooks). There is no mention of prerequisites like ensuring the mailbox exists or that the URL is reachable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a member from an org. Requires an active owner membership. Removing the org's only active owner fails with 409 LAST_OWNER.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The org id. | |
| principal_id | Yes | The member principal id to remove. Removing the org's only active owner fails with `409 LAST_OWNER`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses important behavioral traits: required owner membership and failure on removing the only active owner. It could add more details on side effects or idempotency.
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, front-loaded with the action, and every sentence adds value without unnecessary 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?
For a simple removal tool with 2 parameters and no output schema, the description covers core behavior, prerequisites, and an error scenario. Lacks detail on return value or atomicity, but sufficient for most contexts.
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. The description adds no new parameter info beyond the schema; the error mention is already in the principal_id 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 action ('remove a member from an org') and the resource (org member), distinguishing it from siblings like add_org_member and set_org_member_role.
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 clear context: prerequisite (active owner membership) and a specific failure condition (LAST_OWNER). However, it does not explicitly state when not to use it or compare to alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or clear an organization's display label (PATCH /orgs/v1/:org_id). Owner-only + step-up gated. Pass display_name: null (or "") to clear. Returns the updated org_id, display_name, tier, lease_started_at, and lease_expires_at. Params: org_id, display_name.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The org id to rename. | |
| display_name | Yes | New label. Pass `null` or an empty string to clear the label. Owner-only + step-up gated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses auth requirements and response fields, but could mention reversal or further 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?
Concise, front-loaded with main action, no redundant sentences.
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 simple update tool with two required params, the description includes auth context, clearing behavior, and return fields, making it 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%, so description adds minimal extra meaning beyond what's already in the parameter 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?
Description clearly states 'Set or clear an organization's display label' with HTTP method and endpoint, distinguishing it from sibling tools like rename_project.
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 clear context: 'Owner-only + step-up gated' and how to clear the label, but doesn't explicitly mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a project (PATCH /projects/v1/:id) — fix an auto-generated name. Authorization is org-membership based (admin+ on the owning org, or a project:write grant) and authorize-before-reveal: an unauthorized or guessed id returns the same 403 as a real-but-unauthorized project, never a not-found oracle. Uses the wallet's SIWX auth (not a project service key), so it works even if the project isn't in the local key store. The server validates the name (non-empty, ≤ 200 chars, no control characters).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | New display name (1-200 characters, no control characters; server-validated). | |
| project_id | Yes | The project ID to rename (prefix: prj_). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Covers auth mechanism, authorize-before-reveal with 403, validation rules, and SIWX auth requirement. No annotations exist, so description carries full burden and does well.
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 well-structured sentences with no fluff. First sentence gives purpose, second auth details, third security and validation.
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?
Missing return value description. For a rename tool without output schema, success/failure behavior beyond auth should be explained.
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 good descriptions. Description adds validation details but doesn't significantly enhance 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 'Rename a project' with HTTP method and resource. Specifies use case 'fix an auto-generated name', distinguishing it from other project 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?
Provides authorization context (org-membership, grant, SIWX auth) and security behavior. Does not explicitly list alternatives but context implies when to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extend a contained branch project's TTL.
| Name | Required | Description | Default |
|---|---|---|---|
| ttl_days | No | New TTL extension in days. | |
| project_id | Yes | Parent project ID. | |
| branch_project_id | Yes | Branch project ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It only states 'extend TTL' but does not disclose side effects, permission requirements, reversibility, or default behavior when ttl_days is omitted. This is insufficient for a mutation tool.
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 with no waste, front-loading the core action. However, it is almost too minimal, lacking details that could be included without bloat.
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 lack of annotations and output schema, the description is incomplete. It does not explain TTL, prerequisites (e.g., branch must exist), error conditions, or return value. Important context for an agent to correctly invoke the tool is missing.
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 parameter descriptions. The tool description does not add extra meaning beyond the schema; it merely contextualizes the action. Baseline 3 is appropriate as the description adds no additional parameter value.
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 'extend' and identifies the resource as 'contained branch project's TTL', which clearly distinguishes it from sibling tools like create or delete branch. However, 'contained' is ambiguous (likely means a branch within a project), and TTL is not explained.
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 is provided on when to use this tool versus alternatives (e.g., create_project_branch for initial setup, delete_project_branch for removal). No prerequisites or context for use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request free testnet USDC from the Run402 faucet (Base Sepolia). Rate limit: 1 per IP per 24h. Returns 0.25 USDC — enough for 2 prototype databases.
| Name | Required | Description | Default |
|---|---|---|---|
| address | No | Wallet address (0x...) to fund. If omitted, reads from local agent allowance file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the rate limit, the amount of USDC returned, and its purpose (enough for 2 prototype databases). It does not mention error handling or consequences of exceeding rate limits, but is adequate for a simple faucet.
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 serving a purpose: stating the action, providing the rate limit, and specifying the return value. There is no redundancy or irrelevant 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 the tool's simplicity (one optional parameter, no output schema), the description covers the essential aspects: what it does, constraints, and expected result. It does not detail the response format, but that is less critical for a prototype 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?
The input schema has 100% coverage for the single optional parameter 'address'. The description does not add additional meaning beyond what the schema already provides ('Wallet address... If omitted, reads from local agent allowance file.'). Following the baseline rule, score is 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 action ('request'), the resource ('free testnet USDC from the Run402 faucet on Base Sepolia'), and the amount returned. It uniquely identifies the tool among siblings, as no other tool serves a similar faucet 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 provides explicit rate limiting (1 per IP per 24h) and the return amount, which guides usage. Although it does not mention alternatives or when not to use, the tool's single-purpose nature makes usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a passwordless login email (magic link) to a project user. Auto-creates the user on first verification. Rate limited per email (5/hr) and per project (by tier).
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address to authenticate | ||
| intent | No | Magic-link intent. invite requires the service key and creates trusted invite state. | |
| delivery | No | Email credential mode. Defaults to link. | |
| project_id | Yes | The project ID | |
| client_state | No | Optional opaque app state preserved through token verification | |
| redirect_url | No | Allowed redirect URL. Required for link/both; optional for code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses two important behaviors: auto-creation of user on first verification and rate limits. However, it omits other aspects like idempotency, error scenarios, and whether the tool is read-only or mutating. The description adds value but is not comprehensive.
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 totaling 28 words. Every sentence delivers critical information (action, auto-creation, rate limits) without filler. It is front-loaded with the core purpose and immediately useful constraints.
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 6 parameters, no output schema, and no annotations, the description explains the high-level flow and constraints but does not cover error handling, return values, or detailed behavior for each parameter. It is adequate for a basic understanding but leaves gaps for advanced usage.
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 each parameter's meaning. The tool description does not add new parameter-specific information beyond stating the overall behavior (auto-creation, rate limits). Since the schema is complete, the description's contribution to parameter semantics is minimal, landing at the baseline score.
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 ('Send') and resource ('passwordless login email (magic link)'), clearly distinguishing from sibling tools like 'verify_magic_link' and 'create_auth_user'. It also states the auto-creation behavior, further clarifying the tool's unique role.
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 mentions rate limits (5/hr per email, per project by tier), providing useful guidance on when the tool can be used. It also implies the primary use case (sending a magic link for login) but does not explicitly contrast with alternatives or state 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.
Plan or confirm a project snapshot restore. Omit confirm for the loss statement and confirm token; pass confirm to execute the atomic restore.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | Confirm token from the restore_plan. Omit for a dry restore plan. | |
| project_id | Yes | Project ID to restore. | |
| snapshot_id | Yes | Snapshot ID to restore from. | |
| include_auth | No | When true, restore captured auth users/passkeys too. Sessions/tokens are never restored. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Mentions 'loss statement' and 'atomic restore' but does not clearly state that the current project state will be destroyed or require confirmation details. Lacks full disclosure of consequences.
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, front-loaded with core purpose, no redundant words. Highly efficient for a restore 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?
Covers basic usage but lacks details on return values, required permissions, or what 'loss statement' means. Adequate but with notable gaps for a destructive 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%, so baseline 3. Description adds context for confirm parameter (dry vs execute) but does not elaborate beyond what schema provides for other params.
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 plans or confirms a project snapshot restore, distinguishing two modes. It differentiates from sibling tools like create/delete/list snapshots.
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 tells when to omit or pass the confirm parameter for dry plan vs execution. No mention of when not to use, but the two-mode guidance suffices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query or mutate data via the PostgREST REST API. Supports GET/POST/PATCH/DELETE with query params.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Request body for POST/PATCH (JSON object or array) | |
| table | Yes | Table name to query | |
| method | No | HTTP method | GET |
| params | No | PostgREST query params (e.g. {select: 'id,name', order: 'id.asc', limit: '10'}) | |
| key_type | No | Which key to use: anon (default, respects RLS) or service (bypasses RLS) | anon |
| project_id | No | The project ID (defaults to the active project) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates mutability (POST/PATCH/DELETE) but does not disclose authentication requirements, side effects, rate limits, or data persistence details. The key_type parameter is mentioned only in schema, not description.
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?
Extremely concise (20 words), with purpose front-loaded. Every word earns its place; 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?
Despite 6 parameters and no output schema, description is minimal. It lacks examples, response format hints, or usage patterns. An agent would need more detail to use the tool effectively, especially for constructing queries and handling responses.
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 the concept of 'query params' but does not elaborate on any parameter beyond the method. It provides no additional semantics 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?
Description clearly states the tool queries or mutates data via PostgREST REST API and supports common HTTP methods. However, it does not explicitly differentiate from similar tools like run_sql or contract_read, though the context of REST API vs SQL or contract calls is implied.
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. Given siblings like run_sql (direct SQL) and contract_read (smart contracts), an agent would benefit from context on selecting the appropriate database access method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revoke a per-project capability grant by id. Params: project_id, grant_id. Requires you to be an owner of the project's org.
| Name | Required | Description | Default |
|---|---|---|---|
| grant_id | Yes | The grant id to revoke, e.g. `grt_...`. | |
| project_id | Yes | Project id the grant belongs to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so description must carry full burden. It only states the revocation action without explaining idempotency, error behavior (e.g., if grant doesn't exist), or side effects. Minimal behavioral insight.
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?
Extremely concise: two sentences, no waste. First sentence states action and parameters, second adds prerequisite. Front-loaded and 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?
For a simple two-parameter revocation tool with no output schema, the description covers the core action, required params, and a key prerequisite. Could mention return value or error conditions, but completeness is adequate.
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. The description adds minimal value by mentioning the example `grt_...` for grant_id. Baseline 3 is appropriate as schema already provides parameter 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 action ('Revoke a per-project capability grant by id') and lists required parameters. However, it does not differentiate from related siblings like 'create_project_grant' or clarify the broader context of grants.
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?
Only prerequisite ('Requires you to be an owner') is provided. No guidance on when to use this tool versus alternatives, such as when to revoke vs. create a grant.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a fresh HMAC signing secret for the operator's webhook endpoint. Returned EXACTLY once. Previous secret remains valid for 24h. Requires operator_passkey assurance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses critical behavior: single retrieval, 24h overlap, authentication requirement. With no annotations, it covers essential safety and mutation aspects well, though could elaborate on effect of repeated calls.
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, no wasted words. Front-loaded with action, then key constraints. Every sentence provides unique 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?
Adequately covers behavior and prerequisites for a zero-parameter tool with no output schema. Minor gap: does not describe output format or type of the returned secret.
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?
No parameters exist, baseline is 4. Description adds context about the operation (single return, grace period) that complements the empty 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 action ('Generate a fresh HMAC signing secret') and the specific resource ('operator's webhook endpoint'). It differentiates from sibling webhook tools by specifying 'operator's' rather than mailbox webhooks.
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 key usage constraints: secret returned exactly once, previous valid for 24h, requires operator_passkey. Implicitly guides when to use (for rotation) but does not explicitly contrast with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute SQL (DDL or queries) against a provisioned project. Returns results as a markdown table.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL statement to execute (DDL or DML) | |
| params | No | Bind parameters for parameterized queries (e.g. [42, "hello"]) | |
| project_id | No | The project ID to run SQL against (defaults to the active project) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must disclose safety. It states 'returns results as a markdown table' but does not mention side effects of DDL, permissions needed, rate limits, or error behavior. Critical details for a tool that executes arbitrary SQL.
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, front-loaded with action, no redundancy. Every word earns its place.
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?
No output schema, and the description only states 'returns results as a markdown table' without detail on error handling, pagination, transaction behavior, or response structure. Incomplete for a SQL execution 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. Description adds no parameter-specific details beyond the schema; it does not elaborate on the 'sql', 'params', or 'project_id' 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 uses specific verb 'Execute SQL' and resource 'provisioned project', clearly distinguishing from sibling tools like 'rest_query'. It specifies DDL and queries, and mentions markdown table output.
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 explicit guidance on when to use this tool versus alternatives like 'rest_query'. No when-not-to-use or prerequisite information provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a role-table migration + requireRole gate snippet + first-operator bootstrap for Run402 function role gates. Offline and deterministic (no project or network). Inputs: table, user_col, role_col, roles[], cache_ttl.
| Name | Required | Description | Default |
|---|---|---|---|
| roles | No | Allowed roles. Default: ["operator"]. | |
| table | No | Role table name (unquoted SQL identifier). Default: app_roles. | |
| role_col | No | Role column. Default: role. | |
| user_col | No | User-id column — matches the tenant user id (internal.users.id / JWT 'sub'). Default: user_id. | |
| cache_ttl | No | Role-lookup cache seconds (0-600). Default: 60. 0 = instant revocation (fresh DB read per request). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description's mention of 'offline and deterministic' partially addresses behavioral traits (no network/project interaction). But it does not disclose side effects (e.g., file overwriting, idempotency), output format, or performance characteristics.
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 with zero waste. First sentence states the purpose, second lists inputs and key characteristics. Front-loaded and 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?
No output schema, and description does not explain what the tool returns (e.g., generated code as string, file creation, console output). For a moderately complex tool with 5 parameters and no output schema, this is a significant gap.
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 parameters. The description only lists inputs briefly ('table, user_col, role_col, roles[], cache_ttl') without adding deeper meaning beyond what the schema provides.
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 the tool generates a role-table migration, requireRole gate snippet, and first-operator bootstrap for Run402 function role gates. Verb and resource are specific, and it distinguishes itself from sibling tools which focus on different tasks (e.g., deploy, manage users, etc.).
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?
Description mentions 'offline and deterministic (no project or network)', indicating it's safe for local development and has no external dependencies. However, it does not explicitly state when to use vs alternatives or provide usage exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send an email. Two modes: template (project_invite, magic_link, notification) or raw HTML (subject + html). Optional from_name for display name. Single recipient only. Pass mailbox to target a slug/id; otherwise the configured default_outbound_mailbox_id is used. Result echoes mailbox_id and from_address when the gateway provides them.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Recipient email address (single recipient only) | |
| html | No | HTML email body (raw HTML mode, max 1MB) | |
| text | No | Plain text fallback (raw HTML mode, auto-generated from HTML if omitted) | |
| mailbox | No | Target mailbox by slug or id. If omitted, the configured default_outbound_mailbox_id is used; missing/invalid defaults return typed repair errors. | |
| subject | No | Email subject line (raw HTML mode, max 998 chars) | |
| template | No | Email template (template mode). project_invite, magic_link, or notification | |
| from_name | No | Display name for From header, e.g. "My App" (max 78 chars) | |
| variables | No | Template variables (template mode). project_invite: project_name, invite_url. magic_link: project_name, link_url, expires_in. notification: project_name, message (max 500 chars). | |
| project_id | Yes | The project ID | |
| attachments | No | Binary attachments — RAW HTML MODE ONLY (with subject + html, not template). Max 5; ≤ 7 MB total (decoded). | |
| in_reply_to | No | ID of a prior message (typically inbound) to thread this one under. The server uses it to set RFC-822 In-Reply-To and References headers. Usually set via reply flows; leave empty for new threads. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: two modes, default mailbox fallback, and result echoing mailbox_id and from_address. It does not mention error handling, rate limits, or idempotency, but it covers the main behaviors adequately.
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 only 4 sentences, front-loaded with the core purpose, and free of fluff. Each sentence adds critical information (modes, constraints, mailbox behavior, result). Perfectly concise 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 11 parameters and no output schema, the description covers the main modes and mailbox behavior. However, it fails to mention that attachments are only allowed in raw HTML mode (described in schema but absent here). This is a notable gap for a tool with no annotations and high schema coverage, leaving the agent to infer a key constraint.
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 baseline is 3. The description adds value by explaining the two-mode concept, which clarifies parameter grouping (e.g., template and variables vs subject+html+attachments). It also reiterates mailbox defaulting, but the schema already does that. Overall, it provides a useful framework for parameter selection.
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 sends an email, specifies two modes (template or raw HTML), and includes key constraints like single recipient and mailbox defaulting. It distinguishes itself from sibling tools like 'send_message' by explicitly naming the action and email mode options.
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 guides usage by detailing two modes and their respective parameters (template vs subject+html), and it mentions single-recipient only. However, it does not explicitly compare to alternatives like 'send_message' or state when not to use it, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to the Run402 developers. Requires an active tier.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | Message to send to the Run402 developers |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the prerequisite (active tier) but does not mention side effects, rate limits, or whether the operation is destructive. The behavior is minimally inferred.
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 with no wasted words. The most critical information (action and prerequisite) is front-loaded. Every sentence earns its place.
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 tool is simple with one parameter and no output schema. The description covers the action and a prerequisite but omits any mention of expected outcome, success signals, or error cases. It is adequate but not thorough.
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 the parameter description in the schema ('Message to send to the Run402 developers') matches the tool description almost verbatim. The description adds no additional 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 clearly states the verb 'send' and the resource 'message to the Run402 developers'. This distinct purpose separates it from sibling 'send_email', which sends generic emails.
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?
It mentions the prerequisite 'Requires an active tier', but does not explicitly provide when-to-use or when-not-to-use guidance or alternatives. The distinction from 'send_email' is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Liveness check for the Run402 SERVICE — not your organization. For your organization status (allowance, tier, projects), use status. Reads public GET /health with per-dependency check results. No auth required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that no authentication is required, the endpoint is a public GET /health, and returns per-dependency check results. Without annotations, this provides adequate transparency, though the dependency list is not specified.
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, zero wasted words. The first sentence front-loads the primary purpose and differentiation, and the second adds details and alternative usage. Highly 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?
Given the simplicity of a no-parameter health check, the description is largely complete. It covers what, how, and auth. However, it does not specify the return format or error handling, which could be clarified.
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 no parameters in the schema, the description adds all necessary meaning by explaining the tool's operation. No parameter documentation is needed, and the description fully compensates for the empty 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 is a liveness check for the Run402 SERVICE, explicitly distinguishing it from organization status checks. It uses a specific verb ('liveness check') and resource ('Run402 SERVICE'), and differentiates from the sibling 'status' tool.
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 explicit guidance on when not to use this tool ('not your organization') and directs to the alternative 'status' tool for organization status. This helps agents choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reports on the Run402 SERVICE (availability, capabilities, operator, deployment) — not your organization. For your organization status (allowance, tier, projects), use status. Reads public GET /status. No auth, no allowance required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'Reads public GET /status. No auth, no allowance required'—a clear, accurate disclosure of read-only, public, non-consuming behavior.
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 sentences. First sentence front-loads the tool's purpose; second provides contrast and context. No extraneous 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?
For a simple status check tool with no params and no output schema, the description is complete: it explains scope (service vs org), accessibility (public, no auth), and resource impact (no allowance). Adequate for an agent to select and invoke.
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?
No parameters exist, schema coverage 100%. Baseline for 0 params is 4. Description adds no param info, which is unnecessary; it does mention the HTTP endpoint, but that is not 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 clearly states 'Reports on the Run402 SERVICE (availability, capabilities, operator, deployment)', specifying both the verb 'reports' and the resource 'SERVICE'. It distinguishes itself from the sibling 'status' by noting it is not about the organization.
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 tells when not to use: 'For your organization status (allowance, tier, projects), use `status`.' Also notes 'No auth, no allowance required', guiding the agent on prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register agent contact info (name, email, webhook). New or changed emails start operator email reply verification. Free with allowance auth.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Agent name | |
| No | Contact email (optional; new or changed emails start reply verification) | ||
| webhook | No | Webhook URL for notifications (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description carries the full burden. It discloses that new/changed emails trigger operator email reply verification and mentions 'Free with allowance auth', providing behavioral context about activation and authorization. However, it does not address whether the operation overwrites existing info or requires specific roles.
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 two sentences (or three clauses) that front-load the purpose and include only essential details. Every sentence contributes meaning, with 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?
For a simple setter with 3 params, no output schema, and no annotations, the description covers purpose, a key behavioral trait (email verification), and authorization/cost context. It lacks details on return value or error states, but is largely complete for the tool's simplicity.
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%, with each parameter described in the schema. The description adds only a slight rephrasing of the email parameter's effect (new/changed emails start verification), which is already in the schema. Thus, minimal added value 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 verb 'Register' and the resource 'agent contact info', listing the fields (name, email, webhook). It distinguishes from sibling tools like get_agent_contact_status and verify_agent_contact_email, as it is the only setter.
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 setting or updating contact info and mentions the side effect of email verification, but it does not explicitly state when to use this tool versus alternatives such as get_agent_contact_status (read) or verify_agent_contact_email (verification).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enable or disable automatic email pack repurchase when credits drop below a threshold. Requires a saved Stripe payment method.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The organization ID | |
| enabled | Yes | Enable (true) or disable (false) auto-recharge | |
| threshold | No | Credit threshold to trigger auto-recharge (default 2000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It indicates the tool is a mutator (enable/disable) and specifies a prerequisite, but does not mention side effects, reversibility, or response behavior. This is adequate for a simple toggle but lacks depth.
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, no redundant information, and immediately conveys the core purpose. It is appropriately sized and front-loaded with the action and resource.
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 low complexity (3 parameters, no output schema, no nested objects), the description covers the main aspects: purpose, condition, and a prerequisite. It could optionally mention the return value or confirmation, but the tool's simplicity makes this acceptable.
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 the schema descriptions already explain each parameter. The tool description adds value by linking the threshold to the condition, but does not provide additional semantic context beyond what the schema offers.
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 ('Enable or disable') and clearly identifies the resource ('automatic email pack repurchase'). It also mentions the condition ('when credits drop below a threshold'), distinguishing it from sibling tools that manage other billing aspects.
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 states a prerequisite ('Requires a saved Stripe payment method'), which helps the agent know when it can be used, but it does not provide explicit guidance on when to use this tool versus alternatives like set_low_balance_alert or allowance_create.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the low-balance threshold (in wei) for a KMS signer. Email alerts fire when the signer's native balance drops below this threshold.
| Name | Required | Description | Default |
|---|---|---|---|
| signer_id | Yes | The KMS signer ID | |
| project_id | Yes | The project ID | |
| threshold_wei | Yes | Low-balance threshold in wei (decimal string) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description discloses that email alerts fire on threshold breach, but lacks details on side effects, idempotency, permissions, or error conditions. Adds some context but not full behavioral 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?
Two sentences, clear and front-loaded. No unnecessary words. Every sentence provides 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?
No output schema and no annotations. Description lacks return value, error scenarios, prerequisites. For a tool with 3 required parameters, more context is needed for completeness.
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 100% of parameters with descriptions. The description adds context that threshold_wei triggers email alerts but does not enhance parameter meaning beyond schema. Baseline score 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 action (set threshold), the resource (KMS signer), and the context (email alerts when balance drops). It distinguishes from siblings like check_balance or set_auto_recharge.
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?
Implies usage for monitoring signer balances but does not explicitly state when to use versus alternatives like check_balance or set_auto_recharge. No when-not or context for alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set default_outbound_mailbox_id and/or auth_sender_mailbox_id for a project. Use list_mailboxes first to choose an explicit mailbox id; sending without a mailbox uses the configured outbound default instead of guessing.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID | |
| auth_sender_mailbox_id | No | Mailbox id (`mbx_...`) to use for auth/session emails, or null to clear. | |
| default_outbound_mailbox_id | No | Mailbox id (`mbx_...`) to use for outbound email sends, or null to clear. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions setting or clearing values but lacks details on side effects, permissions, rate limits, or reversibility. For a mutation tool, this is insufficient disclosure.
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 front-load the key action and provide necessary guidance. Every sentence adds value with 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?
With 3 parameters, no output schema, and no annotations, the description adequately explains the tool's purpose and usage hints (like calling list_mailboxes first). It lacks details about return values or confirmation, but is sufficient for basic 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 description coverage is 100%, and the description adds context by explaining the purpose of each parameter and the null option. However, it does not add significant meaning beyond the schema, so a 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?
Description clearly states the tool sets default_outbound_mailbox_id and/or auth_sender_mailbox_id for a project, using a specific verb and resource. It distinguishes from sibling tools like list_mailboxes and send_email by explaining the prerequisite and the effect.
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 tells users to use list_mailboxes first to get a mailbox id, and explains the consequence of not setting defaults. Provides clear context for usage, though it does not explicitly list situations where the tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update operator notification preferences. Cross-wallet effects require email_verified assurance; webhook URL changes require operator_passkey assurance.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | BCP-47 (e.g. en-US) | |
| timezone | No | IANA timezone (e.g. UTC) | |
| webhook_url | No | HTTPS webhook URL (requires operator_passkey assurance) | |
| digest_cadence | No | Periodic digest cadence | |
| digest_hour_utc | No | Hour (UTC) for the digest send | |
| lifecycle_events | No | Which lifecycle events fire notifications | |
| threshold_alerts | No | Threshold-alert delivery mode (immediate ships in v1.5) | |
| digest_day_of_week | No | Day of week for weekly digest (1=Mon, 7=Sun) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden. It discloses that certain operations require specific assurances (email_verified, operator_passkey), which is behavioral. However, it does not mention error behaviors, idempotency, or side effects beyond the constraints.
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, front-loaded sentence with no wasted words. It efficiently communicates the tool's purpose and key behavioral constraints.
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 tool has no output schema, and the description does not mention return values. For an update tool with 8 optional parameters, the description is adequate but could be more complete by indicating success/failure indicators.
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 detailed parameter descriptions. The tool description adds no significant additional meaning beyond repeating the webhook_url assurance already in the schema. Baseline score 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 'Update operator notification preferences' using a specific verb and resource. It distinguishes from the sibling 'get_notification_preferences' by implying a write operation. However, it does not explicitly differentiate from other update tools in the sibling list.
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 important context on assurance requirements for specific changes (cross-wallet effects, webhook URL). However, it does not state when to use this tool versus alternatives or explicitly indicate 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.
Change a member's role (owner > admin > developer > billing > viewer). Requires an active owner membership. Demoting the org's only active owner fails with 409 LAST_OWNER.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | New role: owner > admin > developer > billing > viewer. Requires you to be an active `owner`. | |
| org_id | Yes | The org id. | |
| principal_id | Yes | The member principal id, e.g. `prn_...` (from `list_org_members`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the mutation nature, required ownership, and a specific error case (409 LAST_OWNER). But it does not mention other potential side effects, idempotency, or whether changes take effect immediately. Without annotations, the burden is higher and the description is adequate but not fully transparent.
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, no wasted words, front-loaded with action and hierarchy, and efficiently covers 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?
For a simple mutation tool with no output schema, the description covers the action, prerequisites, and a notable error case. It lacks return value information but is otherwise fairly complete given the tool's 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%, so the schema already describes all parameters. The description adds context for the role hierarchy and notes that principal_id comes from list_org_members, but the schema's role enum description already includes hierarchy. Thus the description adds minimal value 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 action 'Change a member's role' and includes the role hierarchy (owner > admin > developer > billing > viewer), which distinguishes it from sibling tools like add_org_member, remove_org_member, promote_user, and demote_user.
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?
It specifies the precondition 'Requires an active `owner` membership' and a failure condition for demoting the only owner. However, it does not explicitly compare to similar tools like promote_user or demote_user, which could help agents choose the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or clear an organization's default payout wallet for tenant priced routes (PATCH /orgs/v1/:org_id/payout-wallet). Admin/owner-only + step-up gated. wallet_address must already be an active wallet linked to the org; pass null to clear the explicit default. Response includes recovery.status, active_wallet_count, and next_actions for PAYOUT_WALLET_REQUIRED / PAYOUT_WALLET_AMBIGUOUS.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | The org id. | |
| wallet_address | Yes | Active wallet linked to this organization, or null to clear the explicit default. Admin/owner + step-up gated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses endpoint method (PATCH), authorization requirements (admin/owner, step-up), precondition (wallet must be active and linked), and behavior of passing null. It also mentions response fields (recovery.status, active_wallet_count, next_actions). This is sufficiently transparent for a mutation tool.
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, packing necessary information (purpose, prerequisites, behavior, response) into a few sentences without redundancy. It is front-loaded with the core action and endpoint, making it easy to parse.
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 adequately covers the response contents. It mentions prerequisites, required parameters, and the effect of null. For a 2-parameter tool, this is sufficiently complete, though it could optionally mention error scenarios.
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 beyond the schema: it explains the condition on wallet_address ('must already be an active wallet linked to the org') and clarifies that null clears the default. This provides important context that the schema alone does not convey.
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 action: 'Set or clear an organization's default payout wallet'. It specifies the resource (organization's default payout wallet) and the verb (set/clear), and includes the endpoint path. This distinguishes it from siblings like 'link_wallet_to_organization' which links a wallet without setting it as default.
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 clear context on when to use: 'Admin/owner-only + step-up gated' and prerequisites like 'wallet_address must already be an active wallet linked to the org; pass null to clear'. It does not explicitly state alternatives, but the instruction is specific enough that an agent can infer usage. Could be improved by contrasting with 'link_wallet_to_organization'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or clear the optional recovery address used for auto-drain on day-90 deletion of a KMS signer.
| Name | Required | Description | Default |
|---|---|---|---|
| signer_id | Yes | The KMS signer ID | |
| project_id | Yes | The project ID | |
| recovery_address | Yes | 0x-prefixed address (or null to clear). Used for auto-drain on day-90 deletion. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden of behavioral transparency. It clearly states the effect (set or clear address, used for auto-drain on day-90 deletion) and that the address is optional. It does not contradict any annotations. Some additional detail on side effects could further raise the score.
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 concise sentence that conveys the essential action and context without unnecessary words or repetition. Well-structured and 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?
For a simple tool with only three required parameters and no output schema, the description provides sufficient context about the purpose and use case. Nothing essential is missing.
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?
All three parameters have full descriptions in the input schema (100% coverage), so the description adds no new semantic information beyond restating the schema. 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 the verb (set or clear) and the resource (recovery address for a KMS signer) and provides the specific context (auto-drain on day-90 deletion). It distinguishes this tool from siblings like drain_signer.
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 when managing recovery addresses but lacks explicit guidance on when to use versus alternatives like drain_signer. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a project secret (e.g. STRIPE_SECRET_KEY). Values are write-only and injected as process.env variables in functions. Setting an existing key overwrites it. Use this before deploy, then declare the key with secrets.require.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Secret key (uppercase alphanumeric + underscores, e.g. 'STRIPE_SECRET_KEY') | |
| value | Yes | Secret value (will be injected as process.env in functions) | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that values are write-only and injected as process.env, and that setting an existing key overwrites it. Without annotations, this covers the key behavioral traits for a secret-setting operation.
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 concise sentences with no redundancy. Each sentence adds essential information: what it does, behavioral notes, and usage guidance. Perfectly front-loaded with the core action.
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 simple set tool, the description covers the purpose, behavior, and workflow context (before deploy). No output schema needed for a set operation; the description 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?
With 100% schema coverage, the description adds value by explaining the write-only nature and the overwrite behavior, which goes beyond the schema descriptions. The example also helps understanding parameter formats.
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 'Set a project secret' with an example (STRIPE_SECRET_KEY), and explains that it overwrites existing keys. This distinguishes it from related tools like delete_secret or list_secrets.
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 says 'Use this before deploy' and advises to 'declare the key with secrets.require' afterwards, providing good context. However, it does not mention scenarios where this tool should not be used or alternative approaches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Subscribe, renew, or upgrade tier. Auto-detects action based on allowance state. Returns success or payment details if x402 payment is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| tier | Yes | Target tier — subscribes, renews, or upgrades automatically based on wallet state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses auto-detection and potential payment requirement, but fails to mention side effects, error handling, or irreversible actions. With no annotations, more detail is expected for a mutation tool.
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 concise sentences with front-loaded purpose. No redundant 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?
Adequately describes behavior and output for a single-parameter tool without output schema. Missing error cases or preconditions, but 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% and parameter description already mirrors tool behavior. Description adds no new semantic information beyond what the schema provides.
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 subscribes, renews, or upgrades tier, with auto-detection based on allowance state. This distinguishes it from read-only sibling 'tier_status', though no explicit differentiation is given.
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?
Implies usage when changing tier, but no explicit guidance on when to use versus alternatives like 'tier_status' or 'allowance_create'. Lacks exclusion criteria or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change, reset, or set a user's password. Change: provide current_password + new_password. Reset (via magic link login): just new_password. Set (passwordless user): requires allow_password_set=true on project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | The project ID | |
| access_token | Yes | The user's access_token (Bearer token from login) | |
| new_password | Yes | The new password to set | |
| current_password | No | Current password (required for password change, omit for reset via magic link or initial set) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the three behavioral modes and the project-level 'allow_password_set' requirement, though lacks details on side effects or authorization specifics.
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 concise sentences front-loaded with the main purpose; 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 no output schema or annotations, the description covers the main behavioral modes and parameter relationships well, though it omits success/failure indicators.
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% (baseline 3). The description adds meaning by explaining which parameters to use in each mode (e.g., current_password for change, omit for reset/set).
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 three distinct operations (change, reset, set) with specific conditions, clearly distinguishing the tool's purpose from siblings.
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 clear conditions for each usage scenario (change, reset, set), but does not explicitly state when not to use this tool or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Email a short-lived Run402 operator passkey enrollment link to the verified contact email. Requires email_verified.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It notes that the link is 'short-lived', but lacks details about authentication needs, side effects (e.g., invalidating previous links), or what happens after sending.
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, clear sentence with no unnecessary words. It conveys the action, target, and condition efficiently.
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 no parameters and no output schema, the description adequately explains the core function and a precondition. However, it could be more complete by describing what the user receives or next steps.
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?
There are no parameters, and the schema coverage is 100% (empty). The description adds meaning by explaining the action, which is sufficient given no parameters. Baseline for no parameters is 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 the action (email a link), the target (operator passkey enrollment link), and a precondition (email_verified). It effectively distinguishes from sibling tools like delete_passkey or list_passkeys.
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 mentions the requirement 'Requires email_verified', which gives usage context. However, it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or 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.
Full organization snapshot — allowance, billing balance, tier subscription, projects, and active project. Single-call overview.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes output content but discloses no behavioral traits (e.g., read-only nature, required permissions, rate limits, side effects). Minimal 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?
Single sentence, front-loaded with key purpose. Every word adds value. No wasted text.
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 zero-parameter tool lacking output schema, description adequately lists output components. Could mention structured nature or use cases, but sufficient for basic understanding.
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?
Zero parameters with 100% schema coverage. Description adds no parameter info (unnecessary), no deduction needed. Baseline 4 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 clearly states it provides a 'full organization snapshot' listing key components like allowance, billing, tier, projects. Distinguishes from siblings like allowance_status or service_status which are more specific.
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?
Implies use when needing a comprehensive overview ('single-call overview'), but does not explicitly state when not to use or suggest alternatives like allowance_status or tier_status for specific queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a real test notification (audit row marked is_test=true). Rate-limited per wallet at 1/min. Verifies the full pipeline end-to-end.
| Name | Required | Description | Default |
|---|---|---|---|
| source | No | Route the synthetic test event as if it came from the app lane or the platform, so it exercises a specific Telegram routing rule's `source` filter. Defaults to 'platform' when omitted. | |
| event_type | No | Synthetic event_type override (flat snake_case, e.g. `signature_failed`) — use this to exercise a specific routing rule's `event_types` filter precisely. Defaults to the gateway's built-in sample event when omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses important behavioral traits: rate-limited per wallet, audit row marked as test, and end-to-end pipeline verification. It does not mention permissions or response format, but the provided details are adequate for a test tool.
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 with three short sentences, each providing essential information: purpose, rate limit, and verification context. 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?
The description covers the main context: test notification, rate limit, and pipeline verification. However, it does not specify expected outcomes or how to verify success, which would be helpful. Given the tool's simplicity and lack of output schema, it is nearly 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?
The input schema has 100% coverage with detailed descriptions for both parameters (source and event_type). The tool description does not add any additional parameter semantics 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 tool triggers a real test notification with an is_test flag, distinguishing it from other notification tools like create_notification_rule or send_message. It explicitly mentions testing the full pipeline.
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 for testing via 'test notification' and 'verifies the full pipeline end-to-end', but does not explicitly state when to use this tool versus alternatives. It provides rate limit and test flag context but lacks direct usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check current tier subscription — tier name, status, expiry, usage, and function authoring caps when returned (max timeout, memory, scheduled functions, min cron interval). Requires allowance auth.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses auth requirement and return fields, but does not explicitly state it's read-only or mention any side effects, rate limits, or further behavioral details.
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, front-loaded with purpose, no wasted words. 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?
For a simple status check with no params and no output schema, the description adequately covers purpose, return fields, and auth requirement. Could mention if there are any limits or pagination, but not necessary for this 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?
Zero parameters in schema, so baseline is 4. Description adds no parameter info, which is acceptable as there are none.
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 the action (Check) and resource (current tier subscription), listing specific returned fields (tier name, status, expiry, usage, caps). Distinguishes from siblings like allowance_status.
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 a clear prerequisite: 'Requires allowance auth.' Implies usage for checking subscription info, but does not explicitly compare to related tools like allowance_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a function's timeout or memory without re-deploying code. Legacy schedule mutation remains for old simple-function surfaces; new schedule/email background triggers should be declared through ReleaseSpec triggers[].
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Function name to update | |
| memory | No | Memory in MB (tier limits apply) | |
| timeout | No | Timeout in seconds (tier limits apply) | |
| schedule | No | Cron expression (5-field, e.g. '*/15 * * * *') to set or update the schedule. Pass null to remove an existing schedule. | |
| project_id | Yes | The project ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behaviors. It states 'without re-deploying code' indicating nondestructive intent, but does not mention authorization requirements, potential side effects, whether the change is immediate, or if there is any downtime. For a mutation tool, this is insufficient.
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, concise and front-loaded with the main purpose. Every sentence adds value, with no filler. Excellent structure.
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 mutation tool with 5 parameters and no output schema, the description covers the core intent and differentiates legacy vs new but omits return value, error states, or result confirmation. It is adequate but could be more 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 description coverage is 100%, so baseline is 3. The description adds context for the schedule parameter by explaining it is for legacy surfaces, which adds meaning beyond the schema. However, it does not elaborate on memory or timeout limits beyond schema notes.
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 updates a function's timeout or memory without redeploying code. It distinguishes the tool's purpose from code redeployment, and mentions legacy schedule mutation as a secondary use. It does not explicitly differentiate from sibling tools like deploy_function or invoke_function, but the core action is clear.
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 context: use for updating timeout/memory without redeploy, and notes that legacy schedule mutation is for old surfaces while new triggers should use ReleaseSpec. This gives implicit when-not-to-use guidance, though it could be more explicit about when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update per-mailbox settings. Currently supports footer_policy: run402_transparency or none. Prototype projects are locked to run402_transparency; attempting none surfaces the gateway's FOOTER_POLICY_TIER_REQUIRED typed error.
| Name | Required | Description | Default |
|---|---|---|---|
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID | |
| footer_policy | Yes | Outbound footer policy. `none` is allowed for hobby/team projects; prototype projects are locked to `run402_transparency`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description compensates by disclosing that prototype projects are locked to 'run402_transparency' and attempting 'none' surfaces a specific typed error, revealing important behavioral constraints.
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 three sentences, no excess, and the main purpose is front-loaded. However, structure could be improved with bullet points for constraints.
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 3 parameters and no output schema, the description covers input constraints well but does not mention the return format or success behavior, leaving some context missing.
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 supported footer_policy values and the prototype lock, which are not fully covered in the schema's enum 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 updates per-mailbox settings, specifically the footer_policy, and distinguishes itself from other mailbox-related tools (create, delete, get) by focusing on updates.
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 does not explicitly state when to use this tool versus alternatives, but the name and context imply it's for modifying mailbox settings. No exclusion criteria or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a webhook's URL and/or events. At least one field required. Events is a full replacement, not a merge.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | New webhook URL | |
| events | No | New events array (full replacement). Valid: delivery, bounced, complained, reply_received | |
| mailbox | No | Target mailbox by slug or id; omit only when the project has exactly one mailbox. | |
| project_id | Yes | The project ID | |
| webhook_id | Yes | The webhook ID (whk_...) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the critical behavioral trait that 'Events is a full replacement, not a merge', which prevents accidental loss of events. With no annotations, the description carries the behavior disclosure burden. It does not mention other aspects like whether URL validation occurs or if changes are reversible, leaving some gaps.
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 sentences: first states the action and scope, second adds the key constraint 'At least one field required' and the full-replacement behavior of events. No unnecessary words, perfectly front-loaded and 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?
Covers essential information for a straightforward update mutation: what is updated, that events is a full replacement, and that at least one field is required. Missing details like the expected response format (likely success/failure) and prerequisites (e.g., webhook must exist). However, for a simple tool, this is nearly 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 description coverage is 100%, so the input schema already documents all parameters and their meanings. The description reinforces that events is a full replacement, but this is already in the schema ('full replacement'). It adds minimal new meaning beyond the schema, aligning with 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?
Clearly states the action 'Update a webhook's URL and/or events' identifying the resource (webhook) and specific fields. The 'at least one field required' and 'Events is a full replacement, not a merge' further specify scope. Distinguishes from sibling tools like register_mailbox_webhook (create) and delete_mailbox_webhook (delete).
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 the constraint 'At least one field required' which tells the agent that not all fields are mandatory. However, it does not explicitly mention when to use this tool versus alternatives like register_mailbox_webhook for creation or delete_mailbox_webhook for deletion, leaving context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update metadata (description, tags, visibility, fork_allowed) of a published app version.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Updated tags | |
| project_id | Yes | The project ID | |
| version_id | Yes | The version ID to update | |
| visibility | No | Updated visibility | |
| description | No | Updated description | |
| fork_allowed | No | Whether forking is allowed |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It indicates mutation ('update') but lacks details on prerequisites (e.g., must the version be published?), side effects, or permissions. The description lists updatable fields but does not go beyond that.
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 that front-loads the verb and resource, lists the target fields clearly. No unnecessary words or repetition. Excellent conciseness.
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 covers the basic purpose and parameters, but lacks information about return values (no output schema), behavior on failure, or any constraints (e.g., version must be published). For a 6-parameter update tool, this is adequate but not fully 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?
All 6 parameters are described in the input schema (100% coverage), so the schema already provides meaning. The description only repeats the field names without adding extra value like formatting constraints or interdependencies. 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 the action (update), the resource (metadata of a published app version), and specifies the fields that can be updated (description, tags, visibility, fork_allowed). This distinguishes it from sibling tools like delete_version or publish_app.
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 explicit guidance on when to use this tool versus alternatives. The description implies it is for updating a version's metadata, but does not mention when not to use it or suggest alternatives. Given sibling names, the purpose is clear but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate an auth/expose manifest without applying it. This checks the authorization manifest used by manifest.json, database.expose, and apply_expose; it is not deploy-manifest validation. Optional migration_sql is reference context only and is not executed. Use deploy planning/dry-run surfaces for deploy manifest questions.
| Name | Required | Description | Default |
|---|---|---|---|
| manifest | Yes | Auth/expose manifest as a JSON object or JSON string. This is not a deploy manifest. | |
| project_id | No | Optional project id for live-schema validation. Omit for projectless validation. | |
| migration_sql | No | Optional migration SQL used only as reference context for validation; it is not executed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool does not apply the manifest, implying no side effects. It also clarifies that migration_sql is not executed. However, it does not explicitly state read-only nature or any authentication/rate limit details. The information provided is good but could be slightly more explicit.
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, perfectly concise and front-loaded. The first sentence states the core purpose, the second provides usage guidance and clarifications. 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 no output schema, the description does not mention return values, but for a validation tool the output can be inferred. It clearly distinguishes from sibling tools like deploy. The guidance on migration_sql and deploy manifest boundaries adds completeness. Minor gap: no mention of what the validation result looks like.
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% (baseline 3). The description adds meaning by explaining that manifest is the auth/expose manifest used by manifest.json, database.expose, and apply_expose, and that migration_sql is only reference context. This adds value beyond the 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 the tool validates an auth/expose manifest without applying it. It specifies the resource (auth/expose manifest) and the action (validate), and distinguishes it from deploy-manifest validation. This gives a specific verb+resource combination that leaves no ambiguity.
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 the agent when to use this tool (auth/expose manifest validation) and when not to (deploy manifest validation, advising to use deploy planning/dry-run surfaces instead). It also clarifies that migration_sql is only reference context and not executed, preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start or resend the operator email reply challenge for the active agent contact email. Does not expose the challenge secret.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it 'does not expose the challenge secret', which is a useful behavioral note. However, with no annotations, it fails to mention other important traits such as idempotency, side effects, rate limits, or authentication requirements.
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 sentences that front-load the action and add one key behavioral fact. Every word earns its place with 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 zero parameters and no output schema, the description is minimally adequate. However, it lacks information about return values, success/failure indicators, or what happens after the challenge is sent, which an agent would need for reliable invocation.
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 tool has no parameters, and the schema coverage is 100%. The description doesn't need to add parameter details, and its concise note about the challenge secret adds value beyond the empty 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 action ('Start or resend') and the resource ('operator email reply challenge for the active agent contact email'). It is specific and informative, but does not differentiate from sibling tools like 'get_agent_contact_status' or 'set_agent_contact'.
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 initiating or re-sending an email challenge for agent contact verification, but provides no explicit guidance on when to use this tool versus alternatives, nor any preconditions or scenarios where it should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exchange a magic link token for access_token + refresh_token. Creates the user if they don't exist. Token is single-use and expires in 15 minutes.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Six-digit email code. Required with challenge_id. | |
| token | No | Magic-link token. Mutually exclusive with challenge_id/code. | |
| project_id | Yes | The project ID | |
| challenge_id | No | Opaque email-code challenge handle. Required with code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of disclosure. It reveals important side effects (user creation if not exist) and token properties (single-use, 15-min expiry). This goes beyond basic functionality but could mention error scenarios or return format.
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 concise sentences front-load the main action, with no superfluous information. 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?
Given no annotations and no output schema, the description covers the core functionality, side effects, and key constraints. It is complete enough for a simple authentication tool, though missing error conditions and prerequisites.
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 each parameter described adequately. The overall description adds only marginal context about token constraints already implied. Baseline 3 is appropriate as schema carries most of the semantic load.
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 'Exchange' and the resource 'magic link token', and specifies the output (access_token + refresh_token). This distinguishes it from the sibling tool 'request_magic_link' which likely initiates the link.
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 verifying a magic link after requesting it, but does not explicitly state when to use this vs. alternatives like 'request_magic_link'. It mentions token constraints (single-use, 15-min expiry) which provide context but lacks explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a local run402-project-archive.v1 directory or .r402ar tar offline. Checks integrity and compatibility only; archives remain untrusted input.
| Name | Required | Description | Default |
|---|---|---|---|
| archive_path | Yes | Local archive directory or .r402ar tar path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description clearly states the tool only checks integrity and compatibility and treats archives as untrusted input, implying no side effects. This is sufficient for a verification tool.
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, no unnecessary words. Front-loaded with the core action. 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?
Given the single parameter, no output schema, and no annotations, the description covers the tool's purpose, input type, and a key behavioral trait (untrusted input). Could mention return type or error handling but overall sufficient.
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 the single parameter archive_path. The description adds value by clarifying acceptable types (local directory or .r402ar tar path), which is not in the schema description beyond 'path.'
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 verifies a local archive directory or .r402ar tar file, checking integrity and compatibility. It distinguishes from siblings like inspect_project_archive by specifying it only verifies and does not trust input.
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 offline verification but does not explicitly guide when to use this tool over alternatives like inspect_project_archive, import_project_archive, or export_project_archive. No when-not-to-use conditions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Polls the CDN until a MUTABLE blob URL serves the expected SHA-256, or the timeout elapses. For mutable URLs only — for immutable URLs (the immutableUrl returned by assets_put), no waiting is needed; they're bound to a SHA at upload time and never previously cached. Use this after a re-upload to an existing public mutable key when an end-user-visible URL must reflect the new content before continuing. The probe is single-vantage (us-east-1). On timeout, the tool returns isError=true so an agent can branch into a fallback — typically: switch to the immutableUrl.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Mutable blob URL to poll (e.g. https://app.run402.com/_blob/avatar.png) | |
| sha256 | Yes | Expected hex SHA-256 (from a preceding upload) | |
| project_id | Yes | Project ID that owns the URL | |
| timeout_ms | No | Max wait in milliseconds (1 000 – 600 000, default 60 000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits: polls until expected SHA or timeout, only for mutable URLs, single vantage point (us-east-1), and on timeout returns isError=true for fallback branching. Since no annotations are provided, this carries full burden and does so thoroughly.
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 and front-loaded with the main action. It is detailed but every sentence earns its place. Slight verbosity prevents a 5, but it remains 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?
For a polling tool without output schema, the description covers purpose, behavior, constraints, and fallback. It mentions return on timeout but not on success; still adequate given the tool's simplicity.
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 context beyond the schema, e.g., 'sha256' is 'from a preceding upload' and timeout_ms default. This adds semantic value, justifying a score above 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 clearly states the tool polls the CDN until a mutable blob URL serves the expected SHA-256 or timeout. It explicitly distinguishes mutable from immutable URLs, providing a specific verb and 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?
It specifies when to use the tool: after re-upload to an existing mutable key when end-user visibility is required. It also contrasts with immutable URLs where no waiting is needed, and suggests a fallback to immutableUrl on timeout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve the caller's control-plane principal and its org memberships (GET /agent/v1/whoami). A wallet authenticates; ownership is the org. Returns the principal (id/type/displayName/createdAt), authenticator_id, and every org membership (org_id, display_name, role, status). This is the REMOTE identity — for the local wallet/profile state use status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description indicates it's a read-only GET, lists return fields, and implies authentication via wallet. Could explicitly state that no side effects occur, but still clear.
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 with no fluff. HTTP method and path are front-loaded. 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?
For a zero-param tool with no output schema, it adequately describes return fields (principal fields, authenticator_id, org memberships). Could mention error cases or response format, but not required given simplicity.
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?
No parameters, so schema coverage is 100%. Description adds no parameter info, but none needed. Baseline 4 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 resolves the caller's principal and org memberships, with specific verb and resource. Distinguishes from sibling 'status' by noting remote vs local identity.
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 tells when to use this vs 'status': remote identity vs local wallet/profile state. No other guidance needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v4.13.3pay_urlrequest_magic_link4 fields changedInput schema / properties / deliveryAdded value: +{
+ "description": "Email credential mode. Defaults to link.",
+ "enum": [
+ "link",
+ "code",
+ "both"
+ ],
+ "type": "string"
+}Input schema / properties / email / descriptionPrevious value: -"Email address to send the magic link to"New value: +"Email address to authenticate"Input schema / properties / redirect_url / descriptionPrevious value: -"URL to redirect to after clicking the magic link. Must be an allowed origin for this project (localhost, claimed subdomain, or custom domain)."New value: +"Allowed redirect URL. Required for link/both; optional for code."Input schema / requiredPrevious value: -[
- "project_id",
- "email",
- "redirect_url"
-]New value: +[
+ "project_id",
+ "email"
+]verify_magic_link4 fields changedInput schema / properties / challenge_idAdded value: +{
+ "description": "Opaque email-code challenge handle. Required with code.",
+ "type": "string"
+}Input schema / properties / codeAdded value: +{
+ "description": "Six-digit email code. Required with challenge_id.",
+ "type": "string"
+}Input schema / properties / token / descriptionPrevious value: -"The magic link token from the email link URL (?token=...)"New value: +"Magic-link token. Mutually exclusive with challenge_id/code."Input schema / requiredPrevious value: -[
- "project_id",
- "token"
-]New value: +[
+ "project_id"
+]v4.8.0create_notification_ruledelete_notification_rulelist_notification_channelslist_notification_rulestest_notification3 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / event_typeAdded value: +{
+ "description": "Synthetic event_type override (flat snake_case, e.g. `signature_failed`) — use this to exercise a specific routing rule's `event_types` filter precisely. Defaults to the gateway's built-in sample event when omitted.",
+ "type": "string"
+}Input schema / properties / sourceAdded value: +{
+ "description": "Route the synthetic test event as if it came from the app lane or the platform, so it exercises a specific Telegram routing rule's `source` filter. Defaults to 'platform' when omitted.",
+ "enum": [
+ "app",
+ "platform"
+ ],
+ "type": "string"
+}v4.6.0list_project_events2 fields changedInput schema / properties / event_typeAdded value: +{
+ "description": "Restrict to one or more event types, comma-separated (e.g. \"signature_completed,booking_created\"). Composes with source — e.g. source: \"app\" + event_type to watch for one specific business fact.",
+ "type": "string"
+}Input schema / properties / sourceAdded value: +{
+ "description": "Restrict to one source: \"app\" (business facts a deployed function emitted itself via events.emit) or \"platform\" (every non-app source — the platform's own operational record). Omit to read both lanes in one merged, cursor-ordered feed.",
+ "enum": [
+ "app",
+ "platform"
+ ],
+ "type": "string"
+}v4.5.0errors_listv4.4.0list_project_eventsv4.2.1invoke_function4 fields changedInput schema / properties / idempotency_keyAdded value: +{
+ "description": "Stable Idempotency-Key required by paid function invocations. Reuse it for the same paid intent; use a new key only for a new paid intent.",
+ "type": "string"
+}Input schema / properties / poll_interval_msAdded value: +{
+ "description": "Polling interval in milliseconds when wait is true.",
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / timeout_msAdded value: +{
+ "description": "Maximum wait time in milliseconds when wait is true.",
+ "exclusiveMinimum": 0,
+ "type": "integer"
+}Input schema / properties / waitAdded value: +{
+ "description": "When a paid invocation returns a 202 run handle, poll the run and replay the same idempotency key for the retained result.",
+ "type": "boolean"
+}v4.2.0list_tenant_paymentsset_org_payout_walletv4.1.0deploy_verify_edgev4.0.3create_project_branchcreate_project_snapshotdelete_project_branchdelete_project_snapshotdeploy_rehearseget_project_snapshotlist_project_brancheslist_project_snapshotsrenew_project_branchrestore_project_snapshotv4.0.2add_custom_domainapp_upcancel_function_runcheck_domain_statuscreate_function_runcreate_mailbox1 field changedInput schema / properties / slug / descriptionPrevious value: -"Mailbox slug (3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens). Creates <slug>@mail.run402.com"New value: +"Project-scoped mailbox local part (3-63 chars, lowercase alphanumeric + hyphens, no consecutive hyphens). Creates <slug>@<project-mail-host>.mail.run402.com"deploy3 fields changedInput schema / properties / database / properties / migrations / items / properties / id / descriptionPrevious value: -"Stable migration id (e.g. '001_init'). Same id+checksum across re-deploys is a registry noop; same id+different checksum is a hard error."New value: +"Stable versioned migration id (e.g. '001_init'). Same id+checksum across re-deploys is a registry noop; same id+different checksum is a hard error. Use name instead for generated/idempotent SQL."Input schema / properties / database / properties / migrations / items / properties / nameAdded value: +{
+ "description": "Content-tracked migration name for generated/idempotent SQL. The SDK compiles this to <name>_<sha256(sql)[0:16]>; changed content applies once under a new id and identical re-deploys noop. SQL declared with name MUST be idempotent.",
+ "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
+ "type": "string"
+}Input schema / properties / database / properties / migrations / items / requiredRemoved value: -[
- "id"
-]disable_sender_domain_inbounddomains_activatedomains_applydomains_checkdomains_disconnectdomains_ensuredomains_getdomains_listdomains_repairdomains_test_receiveenable_sender_domain_inboundget_function_logs2 fields changedInput schema / properties / request_id / descriptionPrevious value: -"Only return logs correlated to this routed/function request id, such as req_abc123."New value: +"Only return logs correlated to this routed request id, function run id, or attempt id, such as req_abc123, fnrun_abc123, or fnatt_abc123."Input schema / properties / request_id / patternPrevious value: -"^req_[A-Za-z0-9_-]{4,128}$"New value: +"^(?:req|fnrun|fnatt)_[A-Za-z0-9_-]{4,128}$"get_function_runget_function_run_logslist_custom_domainslist_function_runsproject_infoproject_key_cache_exportproject_key_cache_statusproject_keysredrive_function_runregister_sender_domainremove_custom_domainremove_sender_domainsender_domain_statusv3.6.0accept_project_transferadd_custom_domainadd_org_memberadmin_archive_projectadmin_reactivate_projectadmin_set_lease_perpetualai_moderateai_translateai_usageallowance_createallowance_exportallowance_statusapply_exposeassets_getassets_lsassets_putassets_rmassets_signauth_settingsbilling_historybrowse_appscancel_project_transfercheck_balancecheck_domain_statusci_create_bindingci_get_bindingci_list_bindingsci_revoke_bindingclaim_project_transferclaim_subdomaincontract_callcontract_deploycontract_readcreate_auth_usercreate_checkoutcreate_email_organizationcreate_mailboxcreate_orgcreate_project_grantdelete_functiondelete_mailboxdelete_mailbox_webhookdelete_passkeydelete_projectdelete_secretdelete_signerdelete_subdomaindelete_versiondemote_userdeploydeploy_diagnose_urldeploy_eventsdeploy_functiondeploy_listdeploy_release_activedeploy_release_diffdeploy_release_getdeploy_resumedeploy_sitedeploy_site_dirdiagnose_public_urldisable_sender_domain_inbounddrain_signerenable_sender_domain_inboundexport_project_archivefork_appfunctions_rebuildgenerate_imageget_agent_contact_statusget_appget_contract_call_statusget_emailget_email_rawget_exposeget_function_logsget_mailboxget_mailbox_webhookget_notification_preferencesget_operator_statusget_orgget_quoteget_schemaget_signerget_usageimport_project_archiveinitinitiate_project_transferinspect_project_archiveinvite_auth_userinvoke_functionjobs_canceljobs_download_artifactjobs_getjobs_logsjobs_purgejobs_submitlink_wallet_to_organizationlist_custom_domainslist_emailslist_functionslist_incoming_transferslist_mailbox_webhook_deliverieslist_mailbox_webhookslist_mailboxeslist_notificationslist_org_memberslist_orgslist_outgoing_transferslist_passkeyslist_projectslist_secretslist_signerslist_subdomainslist_versionspasskey_login_optionspasskey_login_verifypasskey_register_optionspasskey_register_verifypreview_project_transferproject_getproject_infoproject_keysproject_usepromote_userprovision_postgres_projectprovision_signerpublish_appredrive_mailbox_webhook_deliveryregister_mailbox_webhookregister_sender_domainremove_custom_domainremove_org_memberremove_sender_domainrename_orgrename_projectrequest_faucetrequest_magic_linkrest_queryrevoke_project_grantrotate_webhook_secretrun_sqlscaffold_rolessend_emailsend_messagesender_domain_statusservice_healthservice_statusset_agent_contactset_auto_rechargeset_low_balance_alertset_mailbox_defaultsset_notification_preferencesset_org_member_roleset_recovery_addressset_secretset_tierset_user_passwordstart_operator_passkey_enrollmentstatustest_notificationtier_statusupdate_functionupdate_mailboxupdate_mailbox_webhookupdate_versionvalidate_manifestverify_agent_contact_emailverify_magic_linkverify_project_archivewait_for_cdn_freshnesswhoamiScored across 198 tools
With 198 tools, many have overlapping or confusingly similar purposes. For example, status, service_status, tier_status, and get_operator_status all sound similar despite different scopes, and a large number of deploy_*, project_*, and notification_* tools create high ambiguity. The detailed descriptions help, but the sheer volume and close names make misselection likely.
Naming conventions are inconsistent: some tools use verb_first (list_projects, create_org), others use noun_first (assets_put, jobs_submit, domains_get), and there are one-off names like init, status, and whoami. Prefixes like mailbox_ and contract_ are not used uniformly across related tools (e.g., create_mailbox vs list_mailboxes vs get_mailbox). This mixed style reduces predictability.
198 tools is an extreme mismatch for any MCP server scope, far exceeding the typical 3-15 well-scoped tools. Even for a comprehensive platform like Run402, this count is overwhelming and impractical for an agent to navigate effectively. The set could be consolidated or split into focused servers.
The tool set is remarkably comprehensive, covering project lifecycle, deployments, functions, storage, auth, email, billing, notifications, and more. There are minor gaps, such as no direct tool to list/delete project auth users and no organization deletion operation, but the overall surface covers the domain thoroughly.
Remote MCP server exposing 330 production AI-agent services for web/data processing, validation, AI utilities, blockchain/crypto utilities, and x402 pay-per-use access.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Accountless pay-per-use sandbox, storage, locks, attestation and handoff. Paid over MCP with x402.
Pay-per-action access to APIs and MCP tools over Lightning L402 and Base USDC x402.
