Skip to main content
Glama
Sign In

Valet

by io.github.valetdotdev
OverviewDiscussionsAdmin

Attach a resource to an app

attach_resource
Idempotent

Attach a resource to an app: a named set of environment variables, such as a database's connection string, that the app reads as secrets. Name the resource. When the organization has none by that name, pass a provider from list_catalog_resources and the first call creates it, returning at once with state provisioning. Call again with the same arguments, env_prefix included, until the state is attached: the call that finds the resource ready attaches it and sets its variables, then asks for a restart if the app is running. The state is attaching while Valet still owes the restart or the variables, and conflicted when a name the resource sets is already set on the app; the answer gives the reason. An existing resource attaches by name alone, including one another app holds. The call is safe to repeat: one name is one resource however many times it is called, and an app can hold several under different names. Pass env_prefix when two resources would set the same variables. Pass vars to set the app's own variables in the same restart, such as settings the app needs beside the database: they are set on the call that attaches, never while the resource provisions or once it is attached, so repeat them on every call. A value given here passes through this conversation; say the user could enter it on the dashboard instead. Read the names an attachment sets from list_catalog_resources before writing the app's code. A new database is empty, so the app creates its own tables, and its URL carries the TLS settings it needs. The app must exist, so publish it first. The running process does not see the variables until the restart completes; get_service shows the attachment's status and when the new process is running. Provisioning takes about a minute; call again every ten seconds. Values are never returned here. Requires connecting a Valet account.

Input Schema

NameRequiredDescriptionDefault
nameYesRequired. The app's name.
planNoThe provider's plan. Omit to use its first plan. Repeat it on every call for one resource.
varsNoThe app's own variables to set in the restart the attach requests, as name to value. They are set on the call that attaches. Leave out the names the resource sets.
secretNoWhether vars are stored as secrets, which are encrypted and never shown again. Omit for true; pass false for plain configuration, readable from the dashboard.
org_nameNoThe Valet organization the app belongs to. Omit to use the organization the account joined first.
providerNoThe provider to create the resource from, from list_catalog_resources. Required when the organization has no resource by this name.
resourceYesRequired. The resource's name in the organization, such as shop-db: 3 to 63 lowercase letters, digits, and hyphens. Repeat it on every call for one resource.
env_prefixNoSet the resource's variables under PREFIX_NAME rather than NAME: an uppercase letter, then up to 31 uppercase letters, digits, and underscores. Omit to use the names as they are. Repeat it on every call for one resource: it applies on the call that attaches.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / provider / description
      Previous value: -"The provider to create the resource from, from list_resource_catalog. Required when the organization has no resource by this name."New value: +"The provider to create the resource from, from list_catalog_resources. Required when the organization has no resource by this name."
  2. Added

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare idempotentHint=true and destructiveHint=false, and the description reinforces that ('safe to repeat: one name is one resource'). It goes well beyond annotations by disclosing the asynchronous provisioning lifecycle (provisioning → attaching → attached), the 'conflicted' failure state, the restart requirement, ~1 minute provisioning time with 10s polling, that values are never returned, and that a Valet account must be connected. Because annotations already carry the safety/idempotency profile, the additive content is largely lifecycle detail rather than the core behavioral contract, so this lands mid-range rather than top.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core definition is front-loaded, but the remainder is a dense single-paragraph run-on mixing lifecycle, polling cadence, collision advice, secret handling, and code-generation guidance. Every sentence carries information, yet the lack of structure (no line breaks or ordering by importance) makes it harder to scan than its length alone requires.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 parameters, a nested object, and no output schema, the description compensates fully: it explains the possible states returned, that values are never returned, that get_service reports attachment status, and what the agent must do between calls. An agent can drive this tool to success without inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantics beyond the schema: env_prefix and plan must be repeated on every call for one resource, vars are applied only on the attaching call and never during provisioning (so they must be repeated), and provider is only needed when the name doesn't yet exist. That materially improves correct invocation over the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (attach a resource to an app) and immediately defines what a resource is — a named set of env vars the app reads as secrets. This clearly separates it from siblings like attach_connector, attach_channel, and attach_skill, which target different object types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-and-how guidance: pass a provider from list_catalog_resources when the org has no resource by that name, repeat calls with identical arguments until state is 'attached', poll every ten seconds, pass env_prefix when two resources would collide on variable names, and publish the app first because it must exist. It also names where to read returned variable names and the status tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Valet toolsInspect
Try in Browser
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources