Get share links, publish and manage websites, artifacts and agents. No account needed.
Attach an organization connector to a website so pages served from that site can call the connector's tools.
Attaching is a grant, and it is wider than it looks: every person who can open the page can call every tool the connector exposes, using the credential Valet holds for it. On a private site that is every member of the organization; on a password-protected or shared one it is everyone holding the password or the link. Valet does not narrow the connector's reach for a page, so attach only what the page needs and check the site's access mode before you do.
Only an organization connector that is an HTTP MCP server — transport sse or streamable-http — can be attached; list_attachable_connectors reports exactly that set. A connector that belongs to a single agent cannot back a page. A page calls the connector by its own name, which is what list_site_connectors reports and what the page's request path carries. Attaching a connector that is already attached changes nothing and is safe to repeat. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Required. The site's name. | |
| org_name | No | The Valet organization the site and the connector belong to. Omit to use the organization the account joined first. | |
| connector | Yes | Required. The organization connector's name. It is also the name a page served from the site calls it by. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description substantially expands on the annotations by explaining the grant-like nature of attaching, the security implications of who can call tools, and the fact that Valet does not narrow the connector's reach per page. It also explicitly confirms idempotency, matching the idempotentHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then builds necessary security and constraint context. Every sentence carries meaningful information; there is no filler 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 mutation tool with annotations and no output schema, the description is complete. It covers prerequisites, eligibility, security caveats, idempotency, and how to discover attachable connectors, leaving no critical gap for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context about connector eligibility and that the connector name is used by pages, but the parameter-level meaning is already well documented in the schema itself.
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 opens with a specific verb and resource: attach an organization connector to a website, with a clear outcome (pages can call the connector's tools). It further distinguishes itself from siblings by stating that only HTTP MCP server connectors can be attached and that list_attachable_connectors reports exactly that set.
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 explicit guidance on when to attach and what to check beforehand, including the site's access mode and attaching only what the page needs. It also states exclusions (single-agent connectors cannot be used) and names list_attachable_connectors as the way to identify eligible connectors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one tool on a connector attached to a website and return what the connector answered. It is the sampling step of building a page that calls live data: discover, attach, read the schemas, then call one tool for real before you write any page code.
Call it because a schema is not a shape. list_site_connectors gives you each tool's name and argument schema, which is what your call has to satisfy; this tells you what comes back, which is what the page has to parse. Results are text to read, not JSON to assume: many servers answer in markdown tables or prose, some expose a single meta-tool taking a whole command as one string, and a server that completes the handshake can still refuse half its tools when the stored credential's scope does not cover them. One real call settles all three.
This runs the tool for real, with the organization's own credential and whatever side effects the tool has. It is not a dry run and there is no preview: a tool that sends, writes, or deletes will do so. Prefer a read-only tool when you are only learning the shape, and ask the user before running anything that changes their systems.
The connector must already be attached to the site — attach_site_connector does that — and must be an HTTP MCP server. A tool that answers with an error is reported as an error carrying the connector's own text, which is usually the sentence that says what to fix. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments for the tool, as an object matching the tool's own input schema from list_site_connectors. Omit it for a tool that takes none. | |
| site | Yes | Required. The site's name. | |
| tool | Yes | Required. The tool to run, spelled exactly as list_site_connectors reports it. | |
| org_name | No | The Valet organization the site belongs to. Omit to use the organization the account joined first. | |
| connector | Yes | Required. The name the connector is attached under, which is the name a page calls it by. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond annotations: it is not a dry run, side effects are real, error handling carries the connector's text, and results are text not JSON. It also mentions credential usage and preconditions (connector attached, HTTP MCP server, Valet account). This adds significant value beyond the destructiveHint=true and readOnlyHint=false annotations, with 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 well-structured with front-loaded main action, logical flow, and separate paragraphs for different aspects. It is slightly long but every sentence adds value, covering purpose, usage guidance, behavioral notes, and prerequisites. It could be trimmed by a sentence or two, but the length is justified by the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 params, destructive side effects, no output schema), the description is remarkably complete. It covers preconditions, side effects, error handling, response format (text), and credential requirements. It explains the workflow context (sampling step) and when to use alternatives. No gaps remain for an agent to misuse 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?
The input schema has 100% description coverage, so the baseline is 3. The description adds little new parameter-specific meaning beyond what the schema already provides (e.g., 'args' should match the tool's schema from list_site_connectors, 'connector' is the name attached under). While helpful, this is marginal improvement over 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 explicitly states the tool's purpose: 'Run one tool on a connector attached to a website and return what the connector answered.' It also distinguishes itself from sibling tools like list_site_connectors (which gives names and schemas) and attach_site_connector (which attaches the connector), making the unique role 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 clear guidance on when to use this tool: after 'discover, attach, read the schemas' and because 'a schema is not a shape' – this tool reveals the actual response shape. It explicitly contrasts with list_site_connectors and advises to 'prefer a read-only tool when you are only learning the shape' and to 'ask the user before running anything that changes their systems.' The prerequisites (connector attached, HTTP MCP server, Valet account) are also stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create an organization connector from a Valet catalog entry. It is the step after list_catalog_connectors found the entry for the product the user named; attach_site_connector then lets a website's pages call it.
It creates an entry whose credential is a secret. Pass each slot the entry asks for in secrets, as slot name to value. A slot the organization already holds as a secret needs no value here. If a required slot has neither, nothing is created and the answer names the slots still needed.
A key given here passes through this conversation. That is a real cost and it is the user's call to make: if they hand you the key, use it, and say that they could instead enter it on the dashboard's Integrations page, where it goes straight to Valet. The answer names the slots that were filled and never the values in them.
An entry that authorizes in a browser — OAuth, or a Composio toolkit — is not created here. The answer gives the entry's name and the Integrations page, which creates the connector and runs the authorization in one place. An entry the organization already has is reported as already there; no second connector is made. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| entry | Yes | Required. The catalog entry's name, spelled exactly as list_catalog_connectors reports it. | |
| secrets | No | The entry's secret slots, as slot name to value. Valet stores each as an organization secret. A value passed here travels through this conversation; leave it out and point the user at the dashboard's Integrations page when they would rather it did not. A slot the organization already holds needs no value. | |
| org_name | No | The Valet organization to create the connector in. Omit to use the organization the account joined first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the minimal annotations. It discloses that secrets passed in travel 'through this conversation' with a 'real cost', that the answer only names slots filled and 'never the values', that duplicate entries are reported without creating a second connector, and that missing required slots result in no creation with the missing slots named. This is rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but each sentence contributes meaningful operational detail. It is front-loaded with the core purpose and then logically covers workflow, security, and edge cases. While not terse, the density of useful information earns a high score.
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 mutating connector-creation tool with no output schema and minimal annotations, the description covers prerequisites, failure modes, security/privacy implications, duplicate handling, unsupported auth flows, and the relationship to sibling tools. It is sufficiently complete to guide 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?
The input schema already covers 100% of the parameters, so the baseline is 3. The description adds important semantics beyond the schema, such as how to handle secrets ('Pass each slot the entry asks for in secrets, as slot name to value'), that a slot the org already holds needs no value, and that a passed key 'passes through this conversation', which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create an organization connector from a Valet catalog entry' and places it in a workflow: 'It is the step after list_catalog_connectors found the entry...; attach_site_connector then lets a website's pages call it.' This clearly distinguishes it from the catalog-listing and site-attaching 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?
It provides explicit when-to-use context ('the step after list_catalog_connectors') and calls out an important exclusion: 'An entry that authorizes in a browser — OAuth, or a Composio toolkit — is not created here' and directs users to the Integrations page instead. It also notes the prerequisite 'Requires connecting a Valet account.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a website and stop serving it. Identify it by name, which requires connecting a Valet account, or by the site_token returned when it was published anonymously — whoever published a site can always take it down. This cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Give this or site_token. The site's name, which requires a connected Valet account. | |
| org_name | No | The Valet organization the site belongs to. Omit to use the organization the account joined first. | |
| site_token | No | Give this or name. The token returned when the site was published anonymously; it identifies that one site. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint:true and idempotentHint:true; the description adds crucial context: 'Permanently delete', 'cannot be undone', and the identification logic. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence front-loads the core purpose and effect. Every word 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?
For a simple delete tool with strong annotations and no output schema, the description fully covers all essential aspects: action, effect, identification methods, persistence, and scope. No gaps remain.
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. The tool description adds value by explaining the semantics of name vs. site_token (account requirement vs. anonymous token) and org_name optionality. This goes beyond what the schema alone 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 uses a specific verb ('delete') and resource ('website'), clearly distinguishing it from siblings like rename_site or publish_site. It covers the key aspects: permanent removal and stopping serving.
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 two identification methods (name with Valet account vs. site_token from anonymous publish) and who can delete. It implicitly tells when to use this tool (to delete) but does not explicitly contrast with alternatives like updating or deprecating. Still very clear for a delete operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detach a connector from a website, so pages served from that site can no longer call it. The connector itself is left in place for the rest of the organization, and nothing else about the site changes.
This is how the grant attaching made is taken back. While a connector is attached, everyone who can open the page can call every tool it exposes with the credential Valet holds, so detaching is the way to end that reach. A page that still calls the connector starts getting an error, which is the intended outcome. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Required. The site's name. | |
| org_name | No | The Valet organization the site belongs to. Omit to use the organization the account joined first. | |
| connector | Yes | Required. The name the connector is attached under, which is the name a page calls it by. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description carries the behavioral burden well beyond the annotations. It discloses that the connection is removed while the connector itself is preserved, that nothing else on the site changes, that pages attempting to call the connector will error, and that the operation requires a connected Valet account. This goes beyond readOnly/destructive hints and explains what is and is not affected.
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 the core action and effect, followed by useful behavioral context. Some phrasing is slightly redundant — 'This is how the grant attaching made is taken back' and 'detaching is the way to end that reach' cover similar ground — but overall the length is justified by the security and error behavior context.
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?
Complete enough for a mutating tool with no output schema: it explains the intended consequence, the non-effect on the connector and site, the error behavior for still-calling pages, and a prerequisite. The only ambiguity is what exactly 'Requires connecting a Valet account' means operationally, but this is a minor 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 the package parameter. The description mentions the site and connector roles at a conceptual level but does not add detail beyond the schema's own descriptions. 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?
States a specific verb and resource: detaching a connector from a website. It explains the observable effect — pages served from that site can no longer call it — and explicitly distinguishes from deleting or changing other site behavior by noting the connector remains in place and nothing else about the site changes.
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?
Clearly conveys when this tool is appropriate: when the attach grant should be taken back and reach to the connector's exposed tools should end. It gives context about the security implication of attachment and the intended error outcome after detaching, though it does not explicitly name sibling tools or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get how a page served from a Valet site talks to the connectors attached to it. It is the pair to get_design_system: consult that tool for the artifact's identity, this one for how it talks to its connectors. Call it before writing any page code that fetches from a connector.
Returns the same-origin request contract and a paste-whole session helper that handles both sessionless and stateful connectors, plus the rules a page has to follow: handling a 403, recovering a lapsed session, and never caching a response on the caller's behalf.
This needs no Valet account. It answers with static guidance about how pages work — nothing here reads an organization or a site — so an agent can call it before running any OAuth flow.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context beyond those hints: no Valet account required, no organization or site is read, safe before OAuth, and what the returned contract covers (same-origin requests, session helper, 403 handling, session recovery, no caching). This fully discloses the tool's behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses short, purposeful sentences. It is somewhat long with three paragraphs, but each paragraph adds distinct value: what it does, what it returns, and why no auth is needed. No redundant restatement of schema or annotations.
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 input parameters, no output schema, and safe annotations, the description carries the full burden of explaining output and behavior. It clearly describes the return content (request contract, session helper, page rules) and the operational context, leaving an agent with enough information to call it appropriately.
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, so schema coverage is effectively 100% and parameter semantics are not a burden. The description adds value by explaining what the returned artifact means and how it should be used, which is more relevant than parameter documentation for this tool.
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 opens with a specific verb and resource: getting how a page from a Valet site talks to its attached connectors. It explicitly differentiates itself from the sibling get_design_system by framing the pair as identity vs. connector communication, so an agent can distinguish them without opening schemas.
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 gives a concrete trigger: call this before writing any page code that fetches from a connector. It also routes the agent to get_design_system for artifact identity, making the alternative explicit and the selection condition clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the identity brief to follow before you build or substantially rewrite an artifact. Returns the caller's organization design system when it has one, otherwise the Valet default. Honor an artifact form the user requests. Otherwise choose the artifact form and treatment from its audience, job, and material. The design system supplies identity, not structure. Follow it wherever it speaks, subject to the user's explicit request and to safety, accessibility, and medium correctness. Artifact guidance and model judgment decide every choice it leaves open; do not layer the default design system beneath it. Files a user supplies finished are published unchanged, not restyled. By default this requires a connected account. Pass anonymous: true only when building an explicitly anonymous site; no organization is then consulted and the Valet default is returned.
| Name | Required | Description | Default |
|---|---|---|---|
| org_name | No | The Valet organization whose design system to read. Omit to use the organization the account joined first. | |
| anonymous | No | Set true only when building an explicitly anonymous site. No organization is consulted and the Valet default is returned. Omit for the account-first path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavior beyond that: it returns the organization's design system if present, otherwise the Valet default; it explains the connected-account requirement; it specifies that anonymous access skips the organization lookup; and it clarifies that user-supplied finished files are published unchanged. These details give an agent accurate expectations about side effects and fallback 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?
The description is longer than minimal but every sentence earns its place: purpose is front-loaded, and subsequent sentences cover fallback behavior, usage constraints, and exceptions. It is dense rather than rambling, though some phrasing could be tightened without losing meaning.
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 two-parameter read-only tool with no output schema and full parameter documentation, the description covers all essential context: when to call it, what it returns in both default and anonymous modes, the account requirement, how to treat the returned guidance, and an explicit non-obvious behavior ('do not layer the default design system'). No critical gap remains for an agent deciding whether and how to invoke 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 description coverage is 100%, so the schema already documents both parameters ('org_name' and 'anonymous') well. The description mostly restates the schema's guidance about anonymous mode rather than adding new semantic meaning. It therefore meets the baseline for fully covered parameters but does not elevate beyond 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 first sentence states a clear, specific purpose: 'Get the identity brief to follow before you build or substantially rewrite an artifact.' It names the resource (design system), the verb (get), and the intended invocation point, and it is unmistakably distinct from the site/connector 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 explicitly says when to use the tool ('before you build or substantially rewrite an artifact') and gives conditions such as 'Pass anonymous: true only when building an explicitly anonymous site.' It also provides a when-not instruction: 'do not layer the default design system beneath it.' It does not name alternative tools, but the sibling list contains no competing design-system tool, so the absence is not a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one website's URL, access mode, version, and expiry. Identify it by name, which requires connecting a Valet account, or by the site_token returned when it was published anonymously.
A password-protected site reports that it is gated and never its visitor password. Read the password from the Valet dashboard instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Give this or site_token. The site's name, which requires a connected Valet account. | |
| org_name | No | The Valet organization the site belongs to. Omit to use the organization the account joined first. | |
| site_token | No | Give this or name. The token returned when the site was published anonymously; it identifies that one site. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: password-protected sites report as 'gated' and never expose the visitor password, and name-based identification requires a connected Valet account. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs with no wasted words. The first sentence front-loads the primary purpose and return fields, and the second paragraph delivers an important caveat about password-protected sites. Everything included 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?
For a simple getter with three parameters and no output schema, the description covers the return fields, the two identification modes, the account prerequisite for name, and the password behavior. An agent has everything it needs to call the tool correctly without additional documentation.
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 three parameters well. The description reinforces that name requires a connected account and site_token comes from anonymous publishing, but it does not add meaningful new semantics 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 begins with 'Get one website's URL, access mode, version, and expiry,' which uses a specific verb and resource and names the exact fields returned. This clearly distinguishes the tool from siblings like list_sites or publish_site by emphasizing 'one website' and its retrieval 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?
The description provides clear context on how to identify the site—by name (requiring a Valet account) or by site_token (anonymous publication)—and warns that visitor passwords are never returned. It does not explicitly name alternative tools like list_sites for enumeration, but the identification guidance is sufficient for correct selection in most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the organization connectors a website can hold — the discovery step before attach_site_connector.
Only connectors a page can actually call appear: HTTP MCP servers reached over the sse or streamable-http transport. Command connectors and stdio MCP servers are excluded by definition — they run inside an agent's container and no page can reach them — so a connector the organization has that is not listed here cannot back a site.
Pass site to mark which connectors that site already holds; attached connectors stay listed because attaching is idempotent. Tool schemas are not included — attach the connector, then list_site_connectors reports its live tools and their schemas, which is the moment to write the page's calls. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | A site to mark already-attached connectors against. Omit for the plain organization-wide list. | |
| org_name | No | The Valet organization whose connectors to list. Omit to use the organization the account joined first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already marking read-only/idempotent, the description adds significant behavioral context: it explains which connector types are included (HTTP over sse/streamable-http), why excluded ones cannot back a site, that attached connectors remain listed due to idempotency, that schemas are omitted, and that a Valet account connection is required. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses several sentences to explain exclusions, idempotency, and prerequisites. Each sentence adds value, but the length is slightly higher than the minimum needed. Still well-structured and 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?
For a tool with two optional params and no output schema, the description covers necessary context: supported transports, exclusions, idempotent behavior, lack of schemas, and account prerequisite. It is complete for an agent to decide when and how to invoke 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?
Input schema covers both parameters (site, org_name) with clear descriptions, achieving 100% schema coverage. The description only briefly reiterates that 'site' marks already-attached connectors, adding little beyond the schema. 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 lists organization connectors a website can hold, framed as 'the discovery step before attach_site_connector.' This specific verb+resource pair distinguishes it from sibling tools like list_site_connectors, which reports already-attached connectors with schemas.
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 says when to use this tool (before attaching a connector) and provides exclusions (command/stdio connectors) plus a pointer to list_site_connectors for post-attachment schema details. This gives clear when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the connectors Valet curates — the catalog an organization creates a connector from. Reach for it when list_attachable_connectors returned nothing that serves the data a page needs: the organization has no connector for it yet, and this says whether Valet has an entry for the product and what setting it up would take.
Each entry says how its credential arrives. An entry that takes a secret names each slot it asks for and what the slot is. An entry that authorizes in a browser, or connects through Composio, says so — a person completes those on the dashboard's Integrations page, and no answer here can stand in for that.
Each entry also says whether a website's pages could call it. That is a marker, not a filter: an entry only an agent's container can run is still listed, because "Valet has your product, but no page can call it" is a real answer and reporting it as missing is not. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| org_name | No | The Valet organization a connector would be created in. The catalog is the same for every organization; this names the one the answer points the next step at. Omit to use the organization the account joined first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: entries describe credential arrival (secret slots, browser auth, Composio), and includes a marker nuance about page-callable entries. It also mentions the requirement of a connected Valet account. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three paragraphs of moderate length, but each paragraph serves a distinct purpose: purpose/guidelines, entry content, and a nuance about markers. It is front-loaded with the core action. Slightly verbose but still concise for the information conveyed.
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 one optional parameter, no output schema, and 16 siblings, the description covers purpose, usage guidance, entry content, and a prerequisite (connected account). It explains the return format sufficiently to guide an agent, though it does not enumerate all possible fields. Adequate for the 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 schema already documents the single parameter. The description adds value by explaining that omitting 'org_name' uses the account's first organization, which is not in the schema 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?
Description clearly states it lists the connectors Valet curates (the catalog). It uses a specific verb ('list') and resource ('catalog connectors'), and distinguishes itself from the sibling tool 'list_attachable_connectors' by explaining when to use it instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Reach for it when list_attachable_connectors returned nothing that serves the data a page needs' – this is direct guidance on when to use this tool vs. an alternative. It also implies when not to use it (if list_attachable_connectors already yields results).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the connectors attached to a website, each with the tools a page served from that site can call. Read it before writing a page that calls one: the tool names and argument schemas it returns are what the page's own calls have to match, and guessing them produces a page that fails on its first click.
It lists what is attached to this one site, not what the organization has available. A connector nobody attached to this site does not appear here, and attaching one is a separate, deliberate act — it hands the connector's reach to everyone who can open the page.
Each connector says whether a page can call it, and whether the server keeps an MCP session the page must hold — the page runs the initialize handshake, replays the Mcp-Session-Id header, and re-initializes when the session lapses. The broker forwards the handshake and the tool calls, and always hands the page one JSON document per request, whatever framing the server chose. A connector that could not be reached reports its own error and leaves every other row intact, so one expired credential does not hide the rest. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Required. The site's name. | |
| org_name | No | The Valet organization the site belongs to. Omit to use the organization the account joined first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description goes far beyond by detailing error behavior (one failed connector does not hide others), MCP session handling (initialize handshake, session header, re-initialization), and the fact that the broker always returns one JSON document per request. These are critical behavioral traits not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then provides usage guidance and behavioral details. While it is longer than minimal, every sentence adds value and no information is redundant. A slight truncation could be possible, but the structure is clear 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?
Given the tool has no output schema, the description thoroughly explains what the output contains (list of connectors with callable tools, session info) and error handling. It also covers prerequisites and caveats. The annotation coverage (readOnlyHint, etc.) is strong, and the description fills all remaining gaps for a complete 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?
Schema coverage is 100%, so baseline is 3. The description does not add additional meaning for either parameter beyond what the schema already provides (site name, org_name). No extra constraints, formats, or relationships are described.
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 tool lists connectors attached to a website, including the tools each connector makes available to pages. It distinguishes itself from siblings like list_attachable_connectors by clarifying that it only shows connectors already attached to the specific site, not all available organization-wide.
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 when-to-use guidance: read this before writing a page that calls a connector, because the returned tool names and schemas must match exactly. It also explains the scope limitation (only this site, not organization-wide) and mentions the prerequisite of connecting a Valet account.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the websites in a Valet organization: name, URL, access mode, and when each was last published. It is the way to recover a site's name when an earlier publish has scrolled out of the conversation. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| org_name | No | The Valet organization to list. Omit to use the organization the account joined first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=true, idempotent=true, destructive=false, so the satey profile is covered. The description adds value beyond that by extension the connection prerequiisite and by listing the exact fields returned (name, URL, access mode, last published). It makes no claims that contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: the first states the action and output fields, the second gives a real-world use case, and the third states the prerequisite. Information is front-loaded and no word is wasted.
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-only list tool with one optional parameter and no output schema, the description is sufficient. It tells the agent what the operation returns, when to use it, and what is required to use it. Nothing essential for invoking the tool correctly 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 description coverage is 100% and the single parameter org_name is already described clearly in the schema, incluidng the default if omitted. The description doesn't add any additional parameter-level nuance or syntax, so the baseline of 3 is appropriate because the schema 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 opens with a specific verb ('List') and resource ('websites in a Valet organization') and enumerates the returned fields (name, URL, access mode, last published). This clearly distinguishes it from siblings like get_site, which fetches a single site, and list_site_connectors, which lists connectors, by stating the scope as the entire organisation.
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 a concrete use case: recovering a site's name after an earlier publish has scrolled out of the conversation. It also notes the prerequisite of having a connected Valet account. While it doesn't explicitli name alternative tols or state when-not-to-use, the list-scope makes the context clear enough for an agent to select it over more specific site tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish files as a live website on the public internet, served over HTTPS. Use it when a report, essay, slide-like narrative, dashboard, marketing surface, or other static artifact reads better at a live URL than as conversation text. Honor an artifact form the user requests. Otherwise choose the artifact form and treatment from its audience, job, and material. A request for a live URL chooses delivery, not one long scrolling page.
Before building or substantially rewriting an artifact, call get_design_system. The organization design system supplies identity, not structure. Follow it wherever it speaks. Artifact guidance and model judgment decide the remaining choices; do not layer the default design system beneath it. Safety, accessibility, and medium correctness may adapt an identity choice. When the artifact is HTML, render it at 390px and verify the document itself does not overflow. Give wide flex or grid children min-width: 0. Use minmax(0, 1fr) for flexible tracks so local scrollers stay local. When a local scroller is necessary, show a visible cue when more content is available. For a table, keep the identifying column visible when practical or use another narrow-screen representation. Inspect computed foreground and background colors and verify rendered text contrast on every surface; safe tokens do not prove the intended selectors matched. Valet may place a bottom-center dock over the published page. When the page scrolls vertically, give its main scroll container bottom padding or equivalent clearance of about calc(6rem + env(safe-area-inset-bottom)) so the final content can scroll fully above the dock. Do not introduce scrolling solely to create this clearance. For fixed-height or slide-like artifacts, keep essential content and controls away from the bottom center when the composition allows.
title and description are required on every publish, and a call missing either is refused: title names the site for a person, and description says in one sentence what it holds. A site's name becomes part of its URL, so those two are what a reader has to go on wherever the site is listed. Write them for the person who will come back to this page in a month.
Content is text written here: HTML, CSS, JavaScript, Markdown, JSON, SVG. Images, PDFs, video, and other binary assets are not supported on this surface — publish those with the Valet CLI.
Publishing uses a connected Valet account by default and creates a permanent, private site. Pass anonymous: true only when the user explicitly wants a temporary public site. It is public to anyone who has the link, and it may be removed 36 hours after it is created, unless it is claimed. The result carries a claim URL that moves the site into a Valet account and makes it permanent, and a site_token that updates the same site on a later call. Give that token back to revise the site instead of publishing a second copy of it; with an account, give the site's name instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The site's name, which becomes the last segment of its URL, https://<org>.valet.run/<name>. Omit to have one generated. Naming a site that already exists republishes it. Requires a connected Valet account. | |
| files | Yes | Required. The site's files. One file named index.html is the minimum; add more for stylesheets, scripts, or further pages. | |
| title | Yes | Required. What the site is called, written for a person: 'Q3 Migration Audit', not a hostname. It labels the site wherever it is listed, so write the same thing the page's own <title> says. | |
| org_name | No | The Valet organization to publish into. Omit to use the organization the account joined first. | |
| anonymous | No | Set true only when the user explicitly wants a temporary public site without account ownership. Omit for the account-first path, which connects a Valet account when needed. | |
| site_token | No | The token an earlier anonymous publish returned. Give it back to update that same site instead of creating another. | |
| description | Yes | Required. One sentence saying what the site holds, for a person deciding whether to open it. It is shown beside the title wherever the site is listed. | |
| idempotency_key | No | An opaque key of your choosing. Repeating a call with the same key returns the first call's result instead of publishing a second site, which makes a retry safe. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description explains the underlying destructive/overwriting behavior: naming an existing site republishes it, and anonymous sites may be removed after 36 hours. It also reveals the default account-connected permanent private behavior, the claim URL, and the site_token update mechanism, all beyond what the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage, and the structure is logical: purpose, usage, build guidance, required fields, content constraints, and publishing semantics. It is longer than strictly necessary due to the detailed design-system paragraph, but most of that content earns its place by steering artifact behavior before publishing.
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 8 parameters, no output schema, and destructive annotations, the description covers the critical context: required fields, authentication and account behavior, anonymity and lifetime, URL naming, content format limitations, republishing semantics, and the returned claim URL/site_token. An agent has enough information to invoke it correctly and avoid common mistakes.
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, but the description significantly expands meaning for key parameters. It explains why title and description are required and how they affect the URL and listing, clarifies that anonymous:true should only be set on explicit user request, and explains how site_token updates an existing site instead of creating a duplicate.
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 opens with a specific verb, resource, and delivery mechanism: 'Publish files as a live website on the public internet, served over HTTPS.' It also lists concrete artifact types and explicitly carves out binary assets for the Valet CLI, so an agent can distinguish this publishing tool from the connector and site-management 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 gives explicit when-to-use guidance: use when a report, essay, dashboard, or similar static artifact reads better at a live URL. It also gives key exclusions and alternatives: binary assets should go through the Valet CLI, and get_design_system should be consulted before building an artifact. This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a website and move it to https://.valet.run/. The old address stops serving the site and its name becomes available to another site or app in the same organization. Requires connecting a Valet account.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Required. The site's current name. | |
| new_name | Yes | Required. The site's new name. It also becomes the last path segment of the new URL. | |
| org_name | No | The Valet organization the site belongs to. Omit to use the organization the account joined first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the destructiveHint annotation by explaining concrete consequences: the old address stops serving the site, the old name becomes available to other sites or apps, and a Valet account connection is required. This is useful behavioral detail.
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 concise sentences with no filler. The main action and URL effect are front-loaded, followed by important behavioral consequences and a prerequisite. Every sentence adds 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 mutation tool with three parameters, full schema coverage, annotations, and no output schema, the description provides sufficient context: what happens, what becomes unavailable, and what is required before calling. 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?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds little beyond the schema, though it does reinforce that new_name becomes the last path segment and implies the site moves to a new URL.
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 a specific verb ('rename') and resource ('website') while adding the concrete effect: moving the site to a new URL. This clearly distinguishes it from siblings like delete_site, publish_site, and get_site.
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 clear context about when this tool is appropriate: when a site should be renamed and its URL changed. It does not explicitly name alternatives or exclusions, but the behavior is specific enough to imply the intended use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set who can reach a website: public serves it to anyone who has the link, private serves it only to members of the organization that owns it, and password serves it to anyone who enters a shared visitor password. Requires connecting a Valet account.
Password mode takes the password as the password argument. It is a shared visitor password the owner hands to whoever should see the site, not a Valet credential, and it is at most 72 bytes.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Required. The access mode. public serves the site to anyone who has the link. private serves it only to members of the organization that owns it. password serves it to anyone who enters the shared visitor password. | |
| name | Yes | Required. The site's name. | |
| org_name | No | The Valet organization the site belongs to. Omit to use the organization the account joined first. | |
| password | No | The shared visitor password. Required for password mode and rejected for the others. Anyone who enters it can open the site, so a site's owner passes it to whoever should see the page. At most 72 bytes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate idempotency, non-read-only, and non-destructive behavior. The description adds meaningful context beyond that: a Valet-account prerequisite, the clarification that the password is a shared visitor credential rather than a Valet credential, and the 72-byte limit. This does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and mode definitions, and the password clarification is compact. It is slightly redundant with the already-detailed schema descriptions, but it contains no fluff and reads clearly.
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 full schema coverage, useful annotations, and no output schema, the description plus schema gives the agent everything needed to invoke the tool correctly: prerequisite, mode effects, password constraint, and required/optional fields. There is no critical gap for calling 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?
The input schema has 100% parameter coverage and already explains mode semantics and password constraints. The description largely restates the schema's mode and password content rather than adding new parameter-level meaning, so the 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 opens with a specific verb and resource ('Set who can reach a website') and clearly enumerates the three access modes with their effects. It unambiguously states what the tool does, but it does not explicitly distinguish itself from sibling tools such as share_site or publish_site, which prevents a 5.
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 provides a concrete prerequisite ('Requires connecting a Valet account') and explains the scenarios for each mode, so the agent knows when the tool is applicable. However, it does not say when to prefer this tool over alternatives like share_site or publis_site, leaving some routing to inference.
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. Dates show when Glama detected each change.
publish_site1 field changedInput schema / properties / name / descriptionPrevious value: -"The site's name, which becomes part of its URL. Omit to have one generated. Naming a site that already exists republishes it. Requires a connected Valet account."New value: +"The site's name, which becomes the last segment of its URL, https://<org>.valet.run/<name>. Omit to have one generated. Naming a site that already exists republishes it. Requires a connected Valet account."rename_site1 field changedInput schema / properties / new_name / descriptionPrevious value: -"Required. The site's new name. It also becomes the first label of the new URL."New value: +"Required. The site's new name. It also becomes the last path segment of the new URL."attach_site_connector2 fields changedInput schema / properties / connector / descriptionPrevious value: -"The organization connector's name. It is also the name a page served from the site calls it by."New value: +"Required. The organization connector's name. It is also the name a page served from the site calls it by."Input schema / properties / site / descriptionPrevious value: -"The site's name."New value: +"Required. The site's name."call_site_connector3 fields changedInput schema / properties / connector / descriptionPrevious value: -"The name the connector is attached under, which is the name a page calls it by."New value: +"Required. The name the connector is attached under, which is the name a page calls it by."Input schema / properties / site / descriptionPrevious value: -"The site's name."New value: +"Required. The site's name."Input schema / properties / tool / descriptionPrevious value: -"The tool to run, spelled exactly as list_site_connectors reports it."New value: +"Required. The tool to run, spelled exactly as list_site_connectors reports it."create_connector1 field changedInput schema / properties / entry / descriptionPrevious value: -"The catalog entry's name, spelled exactly as list_catalog_connectors reports it."New value: +"Required. The catalog entry's name, spelled exactly as list_catalog_connectors reports it."delete_site2 fields changedInput schema / properties / name / descriptionPrevious value: -"The site's name. Requires a connected Valet account."New value: +"Give this or site_token. The site's name, which requires a connected Valet account."Input schema / properties / site_token / descriptionPrevious value: -"The token returned when the site was published anonymously. It identifies that one site."New value: +"Give this or name. The token returned when the site was published anonymously; it identifies that one site."detach_site_connector2 fields changedInput schema / properties / connector / descriptionPrevious value: -"The name the connector is attached under, which is the name a page calls it by."New value: +"Required. The name the connector is attached under, which is the name a page calls it by."Input schema / properties / site / descriptionPrevious value: -"The site's name."New value: +"Required. The site's name."get_site2 fields changedInput schema / properties / name / descriptionPrevious value: -"The site's name. Requires a connected Valet account."New value: +"Give this or site_token. The site's name, which requires a connected Valet account."Input schema / properties / site_token / descriptionPrevious value: -"The token returned when the site was published anonymously. It identifies that one site."New value: +"Give this or name. The token returned when the site was published anonymously; it identifies that one site."list_site_connectors1 field changedInput schema / properties / site / descriptionPrevious value: -"The site's name."New value: +"Required. The site's name."publish_site5 fields changedInput schema / properties / description / descriptionPrevious value: -"One sentence saying what the site holds, for a person deciding whether to open it. It is shown beside the title wherever the site is listed."New value: +"Required. One sentence saying what the site holds, for a person deciding whether to open it. It is shown beside the title wherever the site is listed."Input schema / properties / files / descriptionPrevious value: -"The site's files. One file named index.html is the minimum; add more for stylesheets, scripts, or further pages."New value: +"Required. The site's files. One file named index.html is the minimum; add more for stylesheets, scripts, or further pages."Input schema / properties / files / items / properties / content / descriptionPrevious value: -"The file's complete text content."New value: +"Required. The file's complete text content."Input schema / properties / files / items / properties / path / descriptionPrevious value: -"Path within the site, relative and with no leading slash: index.html, styles/main.css. It may not contain '..'."New value: +"Required. Path within the site, relative and with no leading slash: index.html, styles/main.css. It may not contain '..'."Input schema / properties / title / descriptionPrevious value: -"What the site is called, written for a person: 'Q3 Migration Audit', not a hostname. It labels the site wherever it is listed, so write the same thing the page's own <title> says."New value: +"Required. What the site is called, written for a person: 'Q3 Migration Audit', not a hostname. It labels the site wherever it is listed, so write the same thing the page's own <title> says."rename_site2 fields changedInput schema / properties / name / descriptionPrevious value: -"The site's current name."New value: +"Required. The site's current name."Input schema / properties / new_name / descriptionPrevious value: -"The site's new name. It also becomes the first label of the new URL."New value: +"Required. The site's new name. It also becomes the first label of the new URL."set_site_access2 fields changedInput schema / properties / mode / descriptionPrevious value: -"public serves the site to anyone who has the link. private serves it only to members of the organization that owns it. password serves it to anyone who enters the shared visitor password."New value: +"Required. The access mode. public serves the site to anyone who has the link. private serves it only to members of the organization that owns it. password serves it to anyone who enters the shared visitor password."Input schema / properties / name / descriptionPrevious value: -"The site's name."New value: +"Required. The site's name."share_site2 fields changedInput schema / properties / emails / descriptionPrevious value: -"The email addresses to share the site with, at most 10 at a time. Sharing again with an address that already has access re-sends the same link rather than creating a second one."New value: +"Required. The email addresses to share the site with, at most 10 at a time. Sharing again with an address that already has access re-sends the same link rather than creating a second one."Input schema / properties / name / descriptionPrevious value: -"The site's name."New value: +"Required. The site's name."call_site_connectorcreate_connectorget_connector_clientlist_catalog_connectorsattach_site_connectordetach_site_connectorget_design_system2 fields changedInput schema / properties / anonymousAdded value: +{
+ "description": "Set true only when building an explicitly anonymous site. No organization is consulted and the Valet default is returned. Omit for the account-first path.",
+ "type": "boolean"
+}Input schema / properties / org_name / descriptionPrevious value: -"The Valet organization whose design system to read. Omit to use the organization the account joined first. With no connected account the built-in default is returned."New value: +"The Valet organization whose design system to read. Omit to use the organization the account joined first."list_attachable_connectorslist_site_connectorspublish_site1 field changedInput schema / properties / anonymousAdded value: +{
+ "description": "Set true only when the user explicitly wants a temporary public site without account ownership. Omit for the account-first path, which connects a Valet account when needed.",
+ "type": "boolean"
+}share_sitepublish_site3 fields changedInput schema / properties / descriptionAdded value: +{
+ "description": "One sentence saying what the site holds, for a person deciding whether to open it. It is shown beside the title wherever the site is listed.",
+ "maxLength": 1024,
+ "minLength": 1,
+ "type": "string"
+}Input schema / properties / titleAdded value: +{
+ "description": "What the site is called, written for a person: 'Q3 Migration Audit', not a hostname. It labels the site wherever it is listed, so write the same thing the page's own <title> says.",
+ "maxLength": 1024,
+ "minLength": 1,
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "files"
-]New value: +[
+ "files",
+ "title",
+ "description"
+]rename_sitedelete_siteget_design_systemget_sitelist_sitespublish_siteset_site_accessClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Publish files and folders to the web instantly: permanent URLs, immutable versions, claim links.
Publish HTML, Markdown, and multi-file sites as shareable URLs instantly via MCP.
Publish HTML, files, or a URL to a permanent public URL, then update it — from any MCP agent.
Publish and manage secure HTML links: PII/secret scanning, batch create, patch edits, analytics.
Add one secure layer between your agents and this server.
Every tool targets a distinct resource and action. The three list_* connector tools are clearly separated by scope (catalog vs attachable vs attached), and the site management tools are unambiguous.
All tool names follow a uniform verb_noun snake_case pattern. Each name directly states the action and object, with no mixed conventions or vague verbs.
16 tools is slightly above the typical well-scoped range, but the set covers two clear domains—site publishing and connector management—and each tool has a distinct role. The count is justified, if a bit heavy.
Site lifecycle is well covered: publish, list, get, rename, delete, access, and share. The connector lifecycle covers create, attach, detach, and call, but lacks delete/update connector operations, which are a minor gap.
