Valet

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

Annotations only cover safety/idempotency flags; the description goes further by disclosing idempotent no-op behavior with a report, the Slack special case that performs no attachment, the auth requirement, and the functional consequence of attaching (events wake the agent). This is behavior an agent could not infer from the schema or 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?

Front-loaded with purpose before discovery guidance, caveats, and prerequisites. Every sentence carries information, though the block is somewhat dense and could be split or tightened for scanning.

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

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

Given a mutation tool with no output schema, the description covers discovery, prerequisites, idempotency, platform-specific edge cases, and the post-attach effect. An agent has everything needed to decide whether to call it and what to expect.

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 all three parameters are already documented, including that org_name defaults to the first-joined organization. The description adds only that the channel name comes from list_channels, which is a minor restatement of the schema's own note.

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 ('Attach an existing organization channel to an agent') plus the observable effect ('the channel's events wake it'). Clearly distinct from siblings like detach_channel, create_channel, and list_channels without needing to open any schema.

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

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

Explicitly routes discovery to list_channels, explains what a webhook channel buys, warns that an already-attached channel is a no-op, and flags that Slack attaches nothing and instead returns steps. Prerequisites (Valet account, Slack app and browser) are named rather than implied.

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

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

Annotations cover safety flags (readOnly=false, idempotent=true, destructive=false) and the description adds substantial context beyond them: the credential reach for websites vs agents, the auth requirement ('Requires connecting a Valet account'), the no-op behavior on repeat attach, and the app/single-agent restrictions.

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 action and its effect, then layered conditions. It is long, but nearly every sentence carries distinct, non-redundant constraint information; only the security-reach paragraph is slightly expansive.

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 preconditions, scope of effect, restrictions, idempotency, and error behavior ('An app cannot hold a connector yet and the call says so'). An agent has everything needed to call 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 description coverage is 100%, so the schema already documents all three parameters and the baseline is 3. The description adds marginal value by noting the page calls the connector by its own name and that org_name defaults to the first-joined organization, but nothing beyond the schema's own text.

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 ('Attach an organization connector to a website or agent') and immediately clarifies the effect ('so it can call the connector's tools with the credential Valet holds'). This distinguishes it cleanly from detach_connector, attach_channel, and the other attach_* 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?

Goes well beyond 'when to use': warns that attaching is a wide grant, tells the agent to attach only what's needed and to check a website's access mode first, and specifies what can/cannot be attached (HTTP MCP server only, no apps yet, single-agent connectors not attachable elsewhere).

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds substantial context the annotations cannot: the asynchronous provisioning state machine (call again until state is 'attached'), the ~1 minute / 10-second polling cadence, that variables are set only on the attaching call, that the app restarts, that values are never returned, and that a Valet account is required.

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 purpose and the create-vs-attach branching are front-loaded and every sentence carries operative detail, so the length is largely earned for an async, idempotent provisioning tool. It is still dense with ~14 sentences, and the aside about a new database being empty and the app creating its own tables is helpful but skippable, keeping it just short of 5.

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 compensates by explaining what the call returns at each stage ('returning at once with state provisioning', the attaching call, values never returned) and where to verify the outcome. For a 6-parameter, open-world, multi-call workflow, an agent has everything needed to sequence the calls correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema by explaining when provider is mandatory, what env_prefix is for (colliding variable names), and the invariant that plan, resource, and env_prefix must be repeated identically on every call for one resource. That repetition requirement is a real semantic constraint not obvious from the parameter list.

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 precise verb+resource and immediately defines what a 'resource' is ('a named set of environment variables, such as a database's connection string, that the app reads as secrets'), which no sibling name conveys. This clearly separates it from attach_channel, attach_connector, attach_skill, and detach/destroy_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 states explicit conditions for each path: pass a provider from list_catalog_resources when the org has no resource by that name, attach by name alone when one exists, pass env_prefix when two resources would collide, and publish the app first because it must exist. It also routes the agent to get_service to confirm the restart and to list_catalog_resources for the variable names.

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

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

Goes well beyond the annotations to disclose that the agent is rebuilt for the change to take effect, that re-attaching an already-attached skill reports no change without a rebuild, and that a name collision is refused with nothing changed. These idempotency/conflict/rebuild behaviors are exactly the context annotations cannot convey, and they are consistent with idempotentHint=true and destructiveHint=false.

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-loads the core action, then layers the skill-format, rebuild, idempotency and error behavior in dense, information-bearing clauses. Slightly long, but each sentence carries distinct behavioral value with 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 mutation tool with no output schema, the description covers the essential unknowns: the trigger (rebuild), idempotent no-op outcome, name-conflict failure mode, scope restriction and auth prerequisite. An agent has everything needed to call it correctly and interpret results.

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 every parameter (name, skill, org_name) is already documented, including the skill reference syntax and the org_name default. The description largely restates the schema's skill format rather than adding new per-parameter meaning, so the 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?

Opens with a specific verb+resource+effect: 'Attach a skill to an agent so the agent can use it.' This distinguishes it cleanly from siblings like detach_skill, get_skill, list_skills and publish_skill without the agent needing to open any schema.

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

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

Explicitly states the skill reference forms (catalog:<name>, org:<name>, bare name, @v<N> pin) and the precondition that an org skill must already exist, naming publish_skill as the way to create one. It also scopes usage ('Skills attach to agents only') and flags the account requirement, leaving no ambiguity about when this tool applies.

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

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

Annotations already mark it as non-read-only, destructive, open-world, and non-idempotent. The description adds rich, non-obvious behavioral detail: it runs for real with no preview, side effects occur, results are text (not JSON) with varied formats, some servers refuse tools due to credential scope, and errors carry the connector's own text. This goes well beyond structured 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 front-loaded with purpose and well-structured into logical paragraphs. Each paragraph addresses a distinct concern (purpose, rationale, side effects, prerequisites, error handling). There is minor redundancy in the side-effects warning ('runs for real' / 'not a dry run'), but overall it is appropriately sized for a complex, destructive tool.

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

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

Given the complexity (destructive, open world, nested args, no output schema), the description is complete. It covers return format, error behavior, prerequisites, side effects, and scope limitations. An agent has everything needed to invoke it correctly and 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%, so the baseline is 3. The description references args matching the tool's input schema from list_connector_tools, but this is already stated in the schema. It adds marginal value by reinforcing the relationship but no new 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?

The description states a specific verb and resource: 'Run one tool on a connector attached to a website and return what the connector answered.' It distinguishes itself from siblings by positioning as the sampling step and explicitly contrasting with list_connector_tools (schema) and attach_connector (attachment). An agent can identify its role without 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?

Explicitly describes when to use it ('before you write any page code'), when not to use it ('Prefer a read-only tool when you are only learning the shape'), and the prerequisites (connector already attached, HTTP MCP server, Valet account). It also names the alternative (list_connector_tools) and advises asking the user before mutations.

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

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

Goes well beyond the annotations: it discloses that both credentials are consumed, that no organization is ever created, how renaming/suffixing works, and what a repeated successful claim reports. This matches and enriches idempotentHint=true rather than contradicting it.

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, then rationale and edge cases. Dense and largely waste-free, though the site_token warning is repeated in the schema and slightly lengthens 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?

For a token-claiming mutation with no output schema, the description covers prerequisites, credential consumption, naming behavior, and the repeat-call outcome. Nothing an agent needs to invoke it 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema by explaining what site_token does instead and reiterating the claim_token requirement contextually. The new_name/org_name semantics are largely mirrored from 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?

Names a specific verb and resource ('Move a site published anonymously into one of the caller's Valet organizations, making it permanent'), and the contrast with publish_site/site_token distinguishes it from siblings. An agent can tell exactly what this does without opening the schema.

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

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

Explicitly states the credential to pass (claim_token, not site_token) and why, notes the prerequisite ('Requires connecting a Valet account'), and covers the repeat-claim case. It also rules out an alternative path (the site_token can never claim).

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

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

Annotations only give the generic safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description goes well beyond by describing the precise idempotent contract ('same kind and settings reports it and changes nothing; different settings are refused'), the no-op behavior for Slack/Telegram, and the fact that it never returns a secret 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?

Front-loaded with purpose and kind enumeration, then prerequisites and edge cases. It is dense with several long sentences but nearly every clause carries actionable information; only minor tightening is possible.

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 multi-kind, no-output-schema creation tool, the description covers the variants, prerequisite ordering (set_env_vars before secret_name), conflict handling, secret handling, and the browser-required fallback. An agent has everything needed to call it correctly or divert to the right sibling.

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 adds operational meaning by tying parameters to workflows: secret_name must reference an env var set via set_env_vars first, and channel_kind values govern branching behavior. 'A webhook without secret_name is refused' restates the schema's 'Required for webhook' but reinforces the failure mode.

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 ('Create a channel on an agent') and enumerates the channel kinds (cron, heartbeat, webhook, mcp, slack, telegram) with what each does. This clearly distinguishes it from siblings like list_channels, destroy_channel, and attach_channel.

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 each channel kind applies and the prerequisites ('set it with set_env_vars on the agent first', 'Requires connecting a Valet account'). It also names the alternative path for conflicts: 'destroy it first' before recreating with different settings.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds substantial context beyond them: secrets pass through the conversation, the answer never echoes values, missing required slots cause nothing to be created, and duplicate/org-owned entries short-circuit. The one soft spot is the dedup statement ("no second connector is made"), which reads as idempotent behavior while idempotentHint is set to false; that mild tension keeps it from a 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?

Purpose and workflow position are front-loaded, and most sentences carry real information (security cost, failure modes, alternate flows). It is long for a 3-parameter tool and restates the "enter it on the dashboard instead" alternative across paragraphs, plus duplicates schema text, so it is efficient rather than maximally tight.

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, yet the description states what the answer reports (filled slot names and never their values, still-needed slots when creation fails, entry name plus Integrations page for browser-auth entries, already-there for existing entries). Combined with the parameter and secret-handling guidance and the account prerequisite, an agent has everything needed to call 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 description coverage is 100% and the schema's own descriptions already cover the entry-name matching rule, the secrets slot-to-value contract, and the org_name default, so the description largely restates structured data. It adds only marginal framing value (e.g., "pass each slot the entry asks for in secrets"). Baseline 3 is appropriate when 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?

Names a specific verb and resource ("Create an organization connector from a Valet catalog entry") and positions it precisely in a workflow: it is the step after list_catalog_connectors and before attach_connector. It also carves out what is explicitly NOT this tool (browser/OAuth/Composio entries), so an agent can distinguish it from siblings like attach_connector, get_connector, and reauthorize_connector without opening another schema.

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

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

Explicit when-to-use (after list_catalog_connectors located the entry for the product the user named), explicit when-not (browser-authorizing entries go to the Integrations page instead), and explicit no-op cases (an entry the org already has is reported as already there). It also states the prerequisite that a Valet account must be connected, and names an alternative flow for users who do not want secrets to transit the conversation.

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

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

Annotations already declare destructive=true and idempotent=true, but the description goes well beyond them: it warns the action is irreversible and should be user-confirmed, documents the refusal-when-held behavior with holder names, states that destroying an already-gone channel is a no-op, discloses the Slack-integration exception, and notes the Valet account requirement.

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 irreversibility warning is correctly front-loaded and almost every sentence carries distinct behavioral information. It is dense and slightly rambling across the scope branches, but there is little pure filler to cut.

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, no-output tool this covers the full decision space: authorization prerequisite, irreversibility, refusal paths, idempotency, and the Slack edge case. Nothing an agent needs to call it safely and 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 coverage is 100%, so the baseline is 3, but the description adds operational meaning by tying the presence/absence of name to which scope is targeted and what happens in each case. It adds little on org_name beyond the schema's default-organization note, keeping it short of a 5.

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 opening sentence gives a specific verb and resource plus scope ('Destroy a channel and its routes'), which immediately separates it from detach_channel or destroy_resource. The conditional branches (with name vs without) further pin down exactly what is being destroyed.

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 routes between this tool and detach_channel in both directions: an org channel held by agents must be freed with detach_channel first, and a channel the agent only holds should be detached rather than destroyed. It also names list_channels and create_channel as the sources of the channels in each scope, so the agent knows when this call applies.

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

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

Annotations already declare destructive/idempotent/not-read-only, and the description adds substantial context beyond them: irreversibility, the exact semantics of deleting an already-absent memory ('reports that it is gone and succeeds'), the interaction with agent deletion, an auth prerequisite, and a prompt-injection caveat about memory content. This is well past the annotation bar.

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?

Multi-sentence and fairly dense, but front-loaded with purpose and identity, and each remaining sentence carries a distinct safety or lifecycle fact (irreversibility, ordering, idempotence, injection warning, auth). Nothing reads as filler, though it could be tightened slightly.

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

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

For a destructive tool with no output schema, the description covers what gets destroyed, error semantics for missing targets, ordering relative to agent deletion, auth requirements, and the injection risk of the content being handled. An agent has everything needed to call 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?

Schema description coverage is 100%, so key/memory/name/org_name are already documented and the tool has no enum or nested structure. The description restates the exactly-one-of-key-and-memory constraint and the id source, which adds marginal reinforcement rather than new semantics, matching the baseline 3 for schema-covered 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?

Names a specific verb and resource ('Destroy one of an agent's durable memories') and immediately defines the two addressing modes (key or id as list_memories shows them), pointing at the sibling that supplies ids. An agent can distinguish this from list_memories/set_memory without opening any schema.

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

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

Gives explicit preconditions ('confirm with the user first, naming the memory') and a selection rule ('pass exactly one of key and memory'), plus lifecycle ordering advice (destroy memories before destroying the agent). It does not name a counter-tool for updating instead of deleting, so the alternative path is implied rather than stated.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds substantial context beyond them: what is actually deleted (releases, source, channels, connectors, drains, mailboxes), what survives (detached resources, sessions, memories), the irreversibility, the protected architect agent, and the no-op answer for a missing name. These are exactly the traits an agent needs before calling a destructive 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 crucial facts are front-loaded ('Permanently destroy... This cannot be undone, so confirm with the user first'), and nearly every sentence carries non-redundant information. It is a single dense paragraph, though, which is heavier to parse than a bulleted when-to-use / what-gets-destroyed structure would be.

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 destructive tool with no output schema, the description covers all parameters, the consequences for each kind, ordering prerequisites, edge cases (nonexistent name, protected architect agent), and even the return implication ('the answer names them for destroy_resource'). Nothing an agent needs to invoke this safely 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%, so the schema itself already documents kind, name, org_name, and site_token, including the kind-refusal behavior and the name/site_token exclusivity. The description mostly restates these, only adding the rationale that a publisher can always take their own site down; so the baseline of 3 is appropriate rather than a value-add.

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?

Opens with a specific verb and resource ('Permanently destroy a website, app, or agent and stop serving it'), and it clearly separates itself from sibling destroyers (destroy_resource, destroy_session, destroy_memory, destroy_channel, destroy_connector) by enumerating exactly what this tool removes versus what the others handle. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives explicit when-to-use and ordering guidance: 'confirm with the user first', 'call destroy_session and destroy_memory first if they should go', and the exclusion 'the architect agent cannot be destroyed'. It also names the alternative tools (destroy_resource, destroy_session, destroy_memory) and the conditions that select them.

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

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

Annotations already declare destructive=true and idempotent=true, yet the description still adds real substance: the transcript is retained, the session cannot be resumed, running sessions are rejected, and re-deleting an already-gone or foreign session reports gone-and-succeeds. It also discloses the Valet account auth requirement, which no annotation covers.

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?

Five tight sentences, front-loaded with the destructive action and immediate consequences before the edge cases and the agent-interaction caveat. Every sentence carries information, though the agent-destruction ordering note is a slight expansion beyond the tool's core job.

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 compensates by spelling out success/failure semantics (refused when running, reported-gone-but-successful when already deleted or foreign-owned) plus the auth requirement. An agent has everything it needs to call this 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 description coverage is 100%, so all three parameters (name, session, org_name) are already documented, including the org_name default behavior. The description adds only the 'naming the session' safety intent, which is a minor gloss over what the schema already states; 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 opens with a specific verb+resource ('Destroy one of an agent's conversation sessions') and immediately narrows scope with what removal means (leaves list_sessions, cannot be resumed). It is clearly separable from siblings like get_session, list_sessions, and the other destroy_* tools for memory/resource/service.

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 explicit preconditions (confirm with the user first, naming the session), a when-not condition (a running session is refused; wait for it to finish), and an ordering rule relative to destroying the agent (destroy sessions first). This is unusually complete routing and sequencing guidance.

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

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

Goes well beyond the annotations: explains that the channel persists for other agents (bounding the destructive scope), states the concrete effect on event delivery, confirms the unattached case is a no-op, and discloses two things annotations cannot carry — the Slack-specific detach-by-app-removal behavior and the requirement to connect a Valet account. Nothing here contradicts destructiveHint=true or idempotentHint=true.

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, and most sentences carry real information (Slack caveat, auth requirement, idempotency). Minor waste in 'which is the intended outcome' and the idempotency sentence partially restating idempotentHint=true.

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 binding-mutation tool with no output schema and full schema coverage, the description covers the outcome, the entity-survival nuance, idempotency, auth prerequisites, and the platform-specific Slack behavior. An agent has everything needed to call it correctly and interpret the result.

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 all three parameters (name, channel, org_name) are already documented in the schema, including that channel is the attach-time name from list_channels. The description adds no syntax, format, or disambiguation beyond that, so the 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?

States a specific verb (detach) and resource (channel) scoped to an agent, and explicitly names attach_channel as the binding it reverses, which separates it from detach_connector/detach_resource/detach_skill. It even clarifies that the channel entity itself survives, which preempts confusion with destroy_channel.

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?

Gives clear when-to-use context (to end an attach_channel binding so the agent stops receiving events) and names the counterpart tool, plus a no-op case for unattached channels. It does not explicitly route the agent away from the sibling detach_* tools, so it falls short of full alternative coverage.

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

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

Goes well beyond the annotations by spelling out the concrete side effects: environment variables are removed, a running app is restarted so it loses them immediately, the resource and its data survive, other apps retain it, and the operation is a no-op when not attached. It also discloses the prerequisite of connecting a Valet account, and its scoping clarifies the destructiveHint (destruction limited to the app's env vars) rather than contradicting it.

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 the action and its immediate effect, then the blast-radius, then the no-op and auth note. Every clause carries information an agent needs; nothing is padded.

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 carries the burden of describing effects and does so fully: env var removal, app restart, resource data preservation, cross-app effects, idempotency, and the account prerequisite. Nothing needed to call it 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%, so the schema already documents name, org_name, and resource. The description adds no parameter-level detail, so the 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?

States a specific verb+resource ('Detach a resource from an app') that cleanly separates it from the sibling attach_resource and from detach_connector/detach_site_connector. An agent can pick it out by name and scope without opening any schema.

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

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

Explains when detaching is a no-op ('Detaching a resource that is not attached changes nothing') and implies the counterpart attach_resource. It gives clear operating context but never explicitly names alternatives or states when NOT to use it (e.g. to remove the resource itself, use a delete tool).

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

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

Goes well beyond the flat destructiveHint=true: it discloses exactly what gets destroyed (a catalog skill attached to this agent alone is deleted with the attachment, while an org skill survives), that the agent is rebuilt, and the auth prerequisite. The idempotency claim also concretely explains the idempotentHint annotation rather than restating it.

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?

Five short sentences, each front-loaded with a distinct fact (action, side effects per skill type, rebuild, idempotency, prerequisite). Nothing is redundant and no sentence fails to earn 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 3-param mutation with no output schema, this covers the consequential behavior: what is destroyed vs preserved, the agent rebuild side effect, no-op behavior, and the account requirement. An agent has everything needed to call it correctly and predict the 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?

Schema description coverage is 100%, so the schema already documents name, skill (including the catalog:<name>/org:<name> ref syntax), and org_name. The description adds no parameter detail beyond that, which is the baseline-3 case when 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?

States a specific verb (detach) and resource (skill from an agent), and distinguishes it from sibling detach_resource/detach_channel and the inverse attach_skill by naming the exact relationship being severed. An agent can identify the operation without opening the schema.

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

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

The 'detaching a skill that is not attached changes nothing' line tells the agent this is safe to attempt blindly, and the org-vs-catalog distinction guides the correct target choice. It stops short of naming an alternative tool or an explicit when-not-to-use, so it is clear context rather than full routing guidance.

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

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

Annotations declare read-only and idempotent; the description adds the critical trap that a working URL does not prove the new release is live, and interprets the starting/crashed deploy states. It also notes the auth requirement (Valet account) and where the failure reason lives.

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 core follow/poll instruction is front-loaded, but the middle section is a dense run-on covering deploy states, state_reason, and failure remediation. It is informative but overstuffed and hard to parse in one read.

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 with no output schema, it explains state values, deploy states, and failure remediation well. It could say more about log access or how much log is returned, but the operational picture 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 adds nothing about build_id or org_name beyond what the schema already states. 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: follows a build started by publish_app, and enumerates exactly what it returns (state, log, release, URL, deploy). It is unambiguously distinct from siblings like get_service or get_source.

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 names publish_app as the producer of the build_id and gives polling cadence (every 10-15 seconds until up/crashed). It does not rule out alternatives or state when NOT to call it, but 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.

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds materially: the redaction contract ('never returns a credential, a header or environment value, or a URL path'), the exact enumerable credential states, and an auth prerequisite ('Requires connecting a Valet account'). Those are behavioral facts an agent cannot derive from 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?

Front-loads purpose, then return contents, then usage triggers, then the redaction guarantee and auth requirement. Dense but every sentence carries distinct information; no filler or restated title.

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 must carry return-value burden and does: it enumerates the fields returned and, unusually, states what is deliberately withheld. Auth prerequisite and failure-investigation use case are both covered, leaving no gap an agent needs before calling.

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 only two params, and the schema already documents org_name's omission default and connector's required status. The description adds no parameter-level syntax or constraint beyond that, so the 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?

States a specific verb and resource ('Read one organization connector') and enumerates the returned facets: kind, transport, catalog entry, credential state, and holders. This clearly separates it from list_connectors (plural enumeration) and call_connector (invocation), so an agent can route without opening a schema.

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

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

Gives two concrete trigger conditions: 'when a connector's calls fail' and 'before destroying one.' That is real when-to-use guidance rather than implication. It does not name sibling alternatives (e.g., list_connectors for browsing), so it stops 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.

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

Annotations already cover the safety profile (readOnly/idempotent/non-destructive), yet the description adds substantial behavioral detail: which fields appear per kind, that fields of other kinds are absent, and critically that a password-gated service reports being gated but never exposes its visitor password. That secrecy guarantee is exactly the kind of trait an agent cannot infer from annotations or 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?

Purpose and identification are front-loaded in the opening sentences, and the per-kind field enumeration is organized and earns its space. It is somewhat long and dense across two paragraphs, but there is no filler and nothing is buried.

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 a low required-parameter count, the description carries the return-shape burden and does so thoroughly, enumerating what each kind returns plus the auth prerequisites for each identifier. Nothing essential for correct invocation 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 name, org_name, and site_token with their mutual-exclusion semantics. The description largely restates these (account requirement, anonymous site token) without adding format, default, or org_name behavior beyond the schema, so the baseline 3 applies.

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

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

The first sentence names a specific verb (Get) and resource (one website, app, or agent) and states the identification key (by name). It is trivially distinguishable from the sibling list_services, which returns many. The description also proactively states the per-kind field shape, so an agent knows exactly what it is retrieving.

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 clearly frames the tool as single-item retrieval and gives the two identification paths (name requiring a connected Valet account, or site_token for anonymously published sites), which is real when-to-use context. It stops short of explicitly naming the alternative (list_services) or an exclusion condition, so it is clear context rather than explicit routing.

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

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

Adds substantial context beyond the annotations: the transcript may contain personal data and secrets with explicit handling guidance, another agent's session reads as not found, and a Valet account must be connected. Annotations already cover the read-only/idempotent safety profile, and the description layers on privacy and access 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 the resource and returned fields, then the events switch, the privacy caveat, and the access note. Dense and mostly waste-free, though the privacy sentence is comparatively long.

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 5-param read tool with no output schema, the description compensates by enumerating return fields and covering auth, cross-agent scope, and the transcript/limit interaction. Nothing an agent needs to call it 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 coverage is 100%, so the baseline is 3, but the description adds ordering semantics the schema omits: events returns the session's FIRST events up to limit (default 50, max 200), clarifying truncation direction.

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 ("Read one of an agent's conversation sessions") and enumerates the returned fields (status, title, channel, message count, timestamps). It clearly separates a single-session read from the list-style siblings, though it never names a sibling tool explicitly.

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?

Gives a clear conditional: pass events:true for the transcript, omit for details alone, with limit bounds. It also states the auth prerequisite and the cross-agent behavior, but does not explicitly contrast with list_sessions or other get_* tools.

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

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

Annotations already declare a safe, idempotent, non-destructive read (readOnlyHint, idempotentHint, destructiveHint=false), so the safety profile is covered. The description nonetheless adds meaningful behavior beyond them: source resolution, the connected-account requirement, the anonymous override, and that binary files are listed but not returned. This is a genuine value-add, but much of the surface-level 'what happens' is already implied by annotations, so a 3 is appropriate; return pagination/format remains unstated.

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?

Four short paragraphs are front-loaded with the core purpose and each block (resolution, return shape, auth) earns its place. It is dense but not padded, though it sits near the upper end of what an agent needs to read before calling.

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 still explains the return surface: the source/org-vs-default provenance, the reason field, supporting files listed by path, and the binary-file caveat. Auth prerequisites and the anonymous exception are stated, so an agent has everything needed to call correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description exceeds that by clarifying the recursive read pattern (re-invoke with the same skill plus a supporting-file path) and by adding the constraint that under anonymous only a well-known name has an answer, a nuance not present in the schema's enum-free param 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?

States a specific verb and resource ('Get one skill by name') and immediately defines the resolution rule (org's own content vs. Valet's default by name). It is clearly distinguishable from list_skills, publish_skill, and attach_skill, which the description and sibling list make obvious.

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?

Gives explicit when-to-use instructions ('Call it with governance before any work and again before any publish') and names the alternatives that feed it ('any name list_skills reports, or any name the governance skill tells you to read'). The anonymous-vs-connected path is also conditionally scoped.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds real behavioral context: path-omitted calls list files, path-present calls return one file's text, binary content is intentionally withheld, and 'publishing its files again rolls back' explains the write-side effect of a read tool. It also discloses the auth prerequisite ('Requires connecting a Valet account'), which annotations cannot express.

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-loads the core action and the list-vs-read branching, with no filler sentences. The motivational line about reading before overwriting is longer than strictly necessary, but it earns its place by establishing when to reach for the 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?

With no output schema, the description carries the return-value burden itself and does so: lists vs single-file text, binary files excluded from output, and the auth prerequisite. Combined with the rollback note and release workflow, an agent has everything needed to call this correctly for a 4-parameter read 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 baseline is 3, but the description adds functional meaning beyond the schema: 'Without path it lists them; with path it returns one file's text' and 'Pass release, a version from list_releases, to read an earlier release instead.' That link between the release parameter and rollback behavior is not 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?

States a specific verb and resource ('Read what is published: the files of a website, app, or agent's active release') and distinguishes itself from siblings by naming list_releases as the source of version numbers and by tying its purpose to the publish_* family. An agent can tell it apart from get_build, get_service, or list_releases without opening the schema.

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

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

Gives a clear use context ('Read before you change something someone else built, so your publish carries their work forward') and a boundary case ('Binary files are listed and not returned'). It does not explicitly say when to prefer this over a sibling like get_service or get_build, so it falls just short of a full when/when-not/alternatives statement.

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

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

Annotations already declare a safe, idempotent read, so this clears the lower bar easily and adds real context: ordering rule (built-ins first), dedup policy, deliberate exclusions (console and email), and the auth prerequisite. It also discloses that each entry signals whether setup can be completed by a call or requires a human in a browser, which is behaviorally material.

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 purpose, then progressively narrower detail. It runs several clauses long and the parenthetical kind list is useful but heavy; nearly every sentence earns its place, though it could be tightened.

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 does carry the burden of describing returns and largely succeeds: it explains what each entry contains and the inclusion/exclusion rules. It stops short of describing the returned fields (names, identifiers, requirement shape), so an agent still can't fully anticipate the payload.

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 org_name parameter is already fully documented in the schema, including the omit-to-default behavior. The description adds nothing about the parameter, which is acceptable at full coverage but earns only 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?

States a specific verb and resource ('List the channel kinds an agent can have') and immediately scopes what each entry conveys ('what each needs before it works: a schedule, a webhook secret, or a browser authorization'). It distinguishes itself from list_channels (kinds vs. instances) and from create_channel by naming what that sibling excludes, so the agent can route without opening a schema.

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

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

Clear discovery context is implied ('what each needs before it works'), plus a named prerequisite ('Requires connecting a Valet account') and a contrast with create_channel. It never explicitly says 'call this before create_channel' or names list_channels as the alternative for existing channels, so the when-to-use is strong but not fully closed.

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

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

Annotations only carry the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: entries disclose how credentials arrive, browser/Composio-auth entries cannot be completed by this answer and require a human on the dashboard, and the website-callable attribute is a marker rather than a filter. The auth prerequisite is also disclosed.

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?

Purpose and routing trigger are front-loaded, and each paragraph carries a distinct point (what it is, what entries disclose, how to read the callable marker). It is longer than typical and includes mild rhetorical padding such as "no answer here can stand in for that."

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 does the work of explaining return-entry semantics and the auth prerequisite, which is adequate for a one-parameter read tool. It remains qualitative about entry fields and says nothing about ordering or result size, so exact shape is still inferred.

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 description never mentions org_name, but schema coverage is 100% and the schema itself explains the default-organization behavior well, so the baseline of 3 applies. No additional syntax or meaning is contributed by the description.

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

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

The description gives a specific verb and resource ("List the connectors Valet curates") and immediately scopes it as the catalog an organization creates a connector from, which is precisely what distinguishes it from list_connectors. An agent can route between the two without opening either schema.

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

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

It explicitly names the trigger ("Reach for it when list_connectors returned nothing that serves the data a page needs") and the alternative sibling. It also states the prerequisite ("Requires connecting a Valet account") and the read-only, idempotent nature of the call.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower; the description still adds value by disclosing the auth prerequisite and a non-obvious ordering rule ('the first being the default') plus the shape of what comes back. It omits pagination/rate-limit behavior, so it is 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 purpose is front-loaded in a single sentence with a colon-delimited enumeration of what it returns, followed by the actionable directive and prerequisite. The enumeration is dense but each item earns its place; the closing 'and follow the guide' is mildly redundant.

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 correctly steps in to describe the return contents (purpose, plans, default ordering, attachment env vars, usage guide) and the auth prerequisite. Only minor gaps remain around result size/pagination and how the optional org_name interacts with what is 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?

There is a single optional parameter with 100% schema description coverage, including the 'omit to use the organization the account joined first' default. The description adds nothing about org_name, so the schema carries the semantics entirely — the baseline 3 applies.

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

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

The description gives a specific verb and a tightly scoped resource ('resource providers this server can provision from'), reinforced by concrete examples (PostgreSQL database, AI model), which implicitly separates it from list_resources or attach_resource. It also enumerates the returned content (purpose, plans, default ordering, attachment env vars, usage guide). It never explicitly contrasts itself with a named sibling, so it stops short of 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 states a clear when-to-use directive: read it before choosing a resource and before writing code that uses one, and follow the guide. It also gives a prerequisite ('Requires connecting a Valet account'). There is no explicit when-not-to-use or named alternative tool, so 4 rather than 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior: 'It never returns a webhook secret' and 'Requires connecting a Valet account.' These are constraints not derivable from the structured 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 opening is well front-loaded, but the sentence 'how to find a channel to attach, or one no agent holds' is a garbled fragment that reads awkwardly and interrupts the otherwise clean two-mode 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?

With no output schema, the description compensates by enumerating the returned row fields (name, kind, status, catalog origin, agents, channel URL) plus the auth prerequisite. Only the sibling-routing gap keeps it from being 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%, establishing a baseline of 3, but the description adds the semantic effect of each parameter's presence/absence and the default-org fallback, clarifying what 'omitting' org_name actually resolves to.

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 gives a specific verb and resource and splits behavior into two clearly-differentiated modes (org-wide listing when 'name' is omitted, per-agent listing when supplied). It does not, however, distinguish itself from the sibling list_catalog_channels even though it mentions the catalog as a 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?

It clearly states the condition that selects each mode: omit 'name' for organization channels, supply 'name' for that agent's channels. No exclusions or named alternatives are given, so an agent gets context but not routing guidance against siblings like list_catalog_channels.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), yet the description adds real context beyond them: the account-connection requirement, the decision to mark (not hide) rows a website cannot hold, and the fact that tool schemas are deliberately excluded. These are non-obvious behaviors an agent could not infer from structured 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?

Front-loads the core purpose and return shape before the constraint paragraphs, and each paragraph earns its place. It is on the longer side and restates some schema-level parameter detail, so it is efficient rather than maximally tight.

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 carries the return-shape burden and does so (name, kind, transport, catalog entry, capability flags per row). It also covers the hosting constraints for websites/apps/agents and the auth prerequisite, leaving nothing essential unstated.

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's explanation of the `name` and `org_name` semantics largely mirrors the schema text. It reinforces intent but adds little syntax or meaning beyond what the schema already documents, so the 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?

States a specific verb and resource ('List the organization's connectors') and enumerates the returned fields (name, kind, transport, catalog entry). It also distinguishes itself from siblings by naming attach_connector and list_connector_tools as the adjacent steps.

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 positions the tool as 'the discovery step before attach_connector' and routes schema lookups to list_connector_tools after attaching. It also states the auth precondition ('Requires connecting a Valet account'), so both when-to-use and prerequisites are covered.

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

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

Goes well beyond the annotations, which only declare a safe read. It discloses auth requirements ('Requires connecting a Valet account'), partial-failure semantics ('A connector that could not be reached reports its own error and leaves every other row intact'), and session semantics the consumer must be aware of (initialize handshake, Mcp-Session-Id replay, re-initialization).

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?

Four paragraphs, front-loaded with the core purpose and value. The MCP session/framing material is dense but relevant to the stated use case of writing a page, though some of it ('the broker forwards the handshake and the tool calls') sits close to the edge of what a caller needs.

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 carries the full burden and does it well: it explains what each row contains (connectors and their callable tools), callability and session indicators, and error behavior. Nothing essential to calling or interpreting 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%, so the schema already documents name, org_name, and connector. The description's 'Pass connector to read one' merely restates the schema's 'to read only that one,' adding no new syntax or format detail. Baseline 3 is appropriate when 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?

States a specific verb and resource ('List the connectors attached to a website, each with the tools a page served from that site can call'). It explicitly differentiates from siblings like list_connectors ('what the organization has available') and get_service ('for an app or agent'), so an agent can route correctly without opening either schema.

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

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

Gives explicit when-to-use ('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'). It also names the alternative for other cases ('for an app or agent, get_service reports what is attached') and the condition for reading a single connector ('Pass connector to read one').

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds genuinely non-structured behavior: secret values are never returned, scope semantics (service vs inherited org), override precedence, and the account-connection prerequisite. These are the kinds of security- and auth-relevant facts an agent cannot infer from 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?

Two dense sentences, with the concrete capability and return shape front-loaded before the operational caveats. Every clause carries information (secret redaction, scope, override, out-of-band mutation, auth), though the second sentence chains several distinct facts and could be split.

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?

There is no output schema, so the description carries the return-value burden and does so by enumerating the fields (name, secret, scope, override). Combined with the auth prerequisite and the redaction rule, an agent has everything needed to call and interpret the result 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% with only two parameters, including the org_name default behavior, so the schema already carries the parameter burden. The description's mention of 'org for one it inherits' is conceptual scope explanation rather than added parameter syntax, so the 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?

States a specific verb and resource ('List the environment variables an app or agent receives') and enumerates the exact fields returned (name, secret flag, scope, override). It also separates itself from the mutation siblings by noting org variables are changed from the dashboard or CLI, not these tools, so an agent can distinguish it from set_env_vars/unset_env_vars.

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?

Explains the context in which the tool applies (variables an app or agent receives) and gives an explicit 'when not' for mutation of org variables. It stops short of naming set_env_vars/unset_env_vars as the alternative for writing, but the routing guidance is clear.

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

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

Annotations already establish the safe read-only profile, and the description adds substantial context beyond them: undocumented return fields (no output schema exists), quota counters against limits, the Valet account prerequisite, plus prompt-injection and privacy handling guidance. This is real behavioral value the structured fields do not carry.

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-loads the listing scope and return shape before the caveats and safety notes; every sentence carries information. It is dense and runs a bit long, but nothing is pure 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?

With no output schema, the description compensates by naming the returned fields and quota counts, and it covers ownership, auth requirements, and data-handling expectations. An agent has everything needed to call it and interpret the result.

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 name and org_name are already fully documented, including the default-org behavior. The description adds nothing about these two parameters (its key/id mention refers to other tools), 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?

States a specific verb (List) plus resource (an agent's durable memories) and even enumerates the returned fields (id, key, content, pinned, expiry) and ordering (newest first). There is only one memory-listing tool among the siblings, so the boundary against set_memory/destroy_memory is 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 routes the agent: pass a key to set_memory to replace, a key or id to destroy_memory to remove, and clarifies that memories belong to agents rather than websites/apps. Missing an explicit 'when not to use this' statement, but the context for invocation is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, and the description adds genuinely new context beyond them: membership and invitation contents, the sorting order, the meaning of the default marker, that invitation codes are never exposed, and the account-connection prerequisite. It does not mention pagination or result limits, which is the only notable 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?

Front-loaded with the core action and scope, then layered with return contents, filtering, and prerequisites in a compact block. Sentences are information-dense and mostly earn their place, though the opening clause about the default org is slightly syntactically heavy.

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 carries the return-value burden and does so well: it enumerates members and pending invitations and withholds invitation codes. Combined with the prerequisite and parameter behavior, an agent has everything needed to call this 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% and already documents org_name, so the baseline is 3. The description goes further by explaining the cross-tool significance of the returned names ('Use the names here as org_name on the other tools') and the consequence of omitting it, adding semantics the schema does not carry.

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 ('List the Valet organizations the account belongs to') and adds defining scope details: sorted by name, default org marked. No sibling in the list covers organizations, so there is no ambiguity to resolve, and an agent instantly knows what this returns.

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?

Gives explicit usage context: 'Pass org_name to list one organization' and 'Use the names here as org_name on the other tools', which routes the agent across the toolset, plus a prerequisite ('Requires connecting a Valet account'). It lacks an explicit when-not-to-use clause, but there is no competing sibling for org listing, so this is close to complete.

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

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

The annotations already mark this as a safe, idempotent read, so the bar is met on the safety side; the description then adds genuinely non-obvious traits: results are ordered newest first, exactly one release is flagged active, releases that never went live are silently excluded, and the tool is refused for websites. These are behavioral facts the agent could not infer from annotations or 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 lead sentence front-loads verb, resource, ordering, and returned fields, and the exclusions and auth requirement follow compactly. The rollback-workflow sentence is useful routing rather than filler, though it slightly lengthens the definition beyond pure 'list' semantics. No wasted or redundant phrasing.

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 correctly compensates by enumerating the returned fields and status. It also covers the auth prerequisite, the ordering guarantee, the never-live filtering, and the website refusal, so an agent has everything needed to call it and interpret the result.

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 name, limit (1-100, default 20), and org_name all documented inline, so the schema carries the parameter burden. The description's field list (version, state, commit, created, active) describes outputs, not inputs, and adds no syntax or format guidance for the three parameters. Baseline 3 is appropriate.

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

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

Specific verb (List) plus resource (releases) plus scope (an app's or agent's), and it enumerates the returned fields (version, state, commit, created, active). It also draws a boundary against siblings by stating 'Websites are refused', separating it from the publish_site/claim_site family even though no exact list_releases sibling exists.

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 supplies a concrete alternative path for rollback (read earlier files via get_source with its release argument, then republish), which tells the agent when not to treat this as the rollback tool itself. It also states prerequisites ('Requires connecting a Valet account') and exclusions ('Websites are refused'). It stops short of explicitly ranking itself against the other list_* siblings, so it lands at 4 rather than 5.

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

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

Annotations already cover read-only, idempotent and non-destructive status. The description adds ordering (newest first), the returned field set, the security-relevant guarantee that it never returns a variable value, and the prerequisite that a Valet account must be connected. That is meaningful context beyond 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 front-loaded sentences, each earning its place: what it returns, when to use it, and the two constraints (no variable values, account requirement). Zero 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?

No output schema exists, yet the description enumerates the returned fields and ordering, and adds the auth prerequisite and a safety guarantee. Combined with annotations that cover the read-only profile, an agent has everything needed to call 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%, so org_name and its default behavior are already fully documented. The description's phrase 'the organization's resources' hints at the parameter but adds no syntax or default detail beyond the schema, matching the baseline for a fully-documented 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?

States a specific verb (List) and resource (the organization's resources) plus the scope of returned fields, so the agent knows exactly what it yields. It does not explicitly distinguish itself from the sibling list_catalog_resources, which is the main remaining gap.

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?

Gives concrete when-to-use guidance tied to siblings: find a resource to attach (attach_resource) or one no app holds before deleting it (destroy_resource). Clear context, though it stops short of naming those tools or stating exclusions.

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

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world). The description adds value beyond them by disclosing the returned columns, the per-row 'access mode' signal, and the prerequisite 'Requires connecting a Valet account'. Pagination or result-size behavior is left unstated.

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?

Purpose leads, guidance follows, constraints close — a sensible front-loaded order. There is mild redundancy in 'Each row says its access mode', which repeats the access-mode field already listed in the opening sentence.

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

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

For a read-only list tool with no output schema, the description covers what is returned, how to narrow, and the auth prerequisite. It omits any pagination/limit or ordering caveat, which is the only material 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 both parameters are already documented, including the org_name default. The description's 'Pass kind to narrow to one kind' only restates the schema enum, and org_name is never mentioned, so it adds no meaning beyond the structured 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 gives a specific verb-resource pair (List) over a precisely defined resource set ('every website, app, and agent') and enumerates the fields each row carries (kind, URL, access mode, last published). Combined with the title and the reading guidance, an agent can distinguish this from sibling reads like get_service without opening the schema.

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

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

It states a concrete when-to-use rule: 'the first read when the user names something and you do not know what it is', plus the recovery use case for names scrolled out of context. It does not name the alternative (get_service) or state when not to use it, so it falls short of the explicit routing seen in the top example.

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

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

Annotations already cover read-only/idempotent/non-destructive, and the description goes well beyond them: newest-first ordering, the authentication prerequisite ('Requires connecting a Valet account'), the ownership constraint (sessions belong to agents, not sites/apps), and a PII handling instruction for titles.

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?

Four sentences, front-loaded with purpose and return fields, followed by sibling routing, PII guidance, and the auth prerequisite. Each sentence carries distinct, callable information with 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?

With no output schema, the description fully enumerates the returned fields, states ordering, discloses the auth requirement, and clarifies scope (agents vs. websites/apps). An agent has everything needed to call and interpret 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?

Schema description coverage is 100%, so both parameters (name, org_name) and their defaults are already documented. The description adds no parameter-level detail beyond what the schema states; the 'pass a session id' sentence concerns sibling tools, not this tool's inputs.

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 (list an agent's conversation sessions) plus the ordering (newest first) and the exact fields returned. It is immediately distinguishable from its list_* and get_session/destroy_session 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?

Explicitly routes the agent: 'Pass a session id to get_session to read one, or to destroy_session to delete it,' and adds a when-not condition ('a website or app has none') that tells an agent when this tool is inapplicable.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-derivable facts: results are metadata-only (names and descriptions, not content), and it requires a connected Valet account. It does not discuss result size or pagination, but the added auth and payload-scope context is substantive.

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?

Purpose and scope are front-loaded well, but the description runs long and includes motivational filler ("this is how an organization's own standards reach you without anyone naming them") that does not help an agent invoke the tool. The core facts could be conveyed in two sentences instead of five.

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 correctly characterizes the return shape (rows of names plus descriptions) and states the account prerequisite. Combined with 100% schema coverage on the sole parameter, an agent has what it needs to call this correctly, though it does not say what an empty result means or how many skills to expect.

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 org_name parameter is fully documented in the schema (including the omit-to-use-default behavior). The description adds nothing about the parameter, so the 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?

States a specific verb and resource ("List every skill the organization has") and immediately delimits scope: well-known names plus org-written/catalog-installed skills. It explicitly distinguishes itself from get_skill by noting it returns names and descriptions only while get_skill reads content, so an agent can separate the two without opening either schema.

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

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

Gives a concrete triggering condition (the governance skill directs you to call this and read every skill whose description applies to the work at hand) and names the alternative for content (get_skill). There is no explicit "when not to use" clause, but the read-vs-fetch-content split is a clear routing rule.

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

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

With annotations supplying the safety profile, the description still adds substantial context beyond them: the manifest is validated rather than written, unnamed org connectors/channels are auto-attached, unresolved references cause nothing to deploy and return a pending list with the fixing tool, deploys finish before return, and a Valet account must be connected. The replacement-on-existing-name behavior aligns with destructiveHint=true, and the opt-in idempotency_key is consistent with idempotentHint=false.

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?

Purpose and the agent-vs-site distinction are front-loaded, and every paragraph carries actionable information (preconditions, failure handling, replacement, return behavior). The prose is dense and somewhat mannered, so it is longer than strictly necessary, but it is not padding.

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?

There is no output schema, so the description carries return-value burden and does so: the answer carries the release version and points to get_service for run status. Combined with the auth requirement, failure-mode explanation, and file prerequisites, an agent has everything it needs to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description adds cross-cutting meaning on top: files must contain valet.yaml and SOUL.md at the agent root, and publishing to an existing name replaces its source (clarifying the `name` parameter's republish semantics). This goes beyond restating 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?

States a precise verb+resource ('Publish source as an agent') and immediately differentiates from siblings by describing the artifact shape: a SOUL.md, a valet.yaml with skills/connectors/channels/configuration. It explicitly rules out publish_site/publish_app with 'not a website or an app,' so the agent can route correctly without opening a schema.

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

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

Gives an explicit when-to-use condition ('when the work is an agent that answers on a channel or runs on a schedule, not a website or an app'), a precondition ('Apply the governance skill before calling'), and a prerequisite read ('read get_source first when the agent is not yours'). Alternatives and exclusions are both named.

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

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

Annotations (destructive, open-world, non-idempotent) only flag the risk surface; the description goes far beyond, disclosing overwrite semantics ('Publishing to a name that exists replaces its source'), the refused-call condition, binary-asset limits, build-time dependency installation, the crashed-process behavior (a running release keeps serving, so a live URL does not prove the new release is live), and default privacy.

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?

Four dense paragraphs, all front-loaded with the core definition before operational detail. Nearly every sentence carries unique operational value, though the crashed-process and environment-variable guidance could be tightened. Long but not padded.

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 must explain returns and post-call workflow, and it does: it returns a build id, you poll get_build, and deploy_state gates liveness. It also covers account requirement, first-publish app creation, and access defaults, leaving no structural gap for a 7-parameter mutation 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 already 100%, setting a baseline of 3, but the description adds real semantic weight: the Procfile must be at root, its web type must listen on $PORT which Valet sets, valet.yaml is written from title/description, dependencies come from the published manifest, and the idempotency-key caveat about changed files.

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+resource ('Publish source as an app') and immediately defines what an app is ('a process Valet builds from your files and runs behind its own URL'), which cleanly separates it from publish_site and publish_skill in the sibling list. An agent can tell the three apart without opening any schema.

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

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

Gives explicit when-to-use conditions ('when the work needs a server, a background process, or a database'), a prerequisite ('Apply the governance skill before calling'), and an ordering of alternatives ('read get_source first when the app is not yours', then set_env_vars/attach_resource/set_service_access after). It even routes the agent to get_build for status.

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

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

Annotations already declare destructive/openWorld and non-idempotent, and the description substantially enriches them: default creates a permanent private site, anonymous: true yields a temporary public link that may be removed 36 hours after creation unless claimed, and the result carries a claim URL plus a site_token used to update rather than duplicate. It does not, however, spell out rate limits or exactly what 'destructive' means for an existing named site on republish, so it falls short of a full 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?

Front-loaded with the core action and the usage trigger, then proceeds to governance, required fields, content types, and account semantics in distinct paragraphs. It is on the long side and restates some schema-level facts (title/description required), but nearly every sentence adds a decision-relevant constraint.

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 an 8-parameter mutation tool with no output schema, the description covers the account-vs-anonymous decision, the token lifecycle, the claim URL, the governance prerequisite, and the unsupported-binary constraint — everything an agent needs to invoke it correctly and interpret its result.

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 carries most parameter detail (baseline 3). The description nonetheless adds meaning beyond it: title and description are required on every publish and a call missing either is refused, name becomes the first label of the URL and reuses an existing site on republish, and the claim/token lifecycle for anonymous publishes.

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 ('Publish files as a live website, served over HTTPS at its own URL') and implicitly separates itself from publish_app, publish_skill, and share_site by naming the artifact class (static HTML/CSS/JS/Markdown/JSON/SVG) and the delivery outcome. An agent can select it without opening sibling 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?

Explicit when-to-use criteria ('when a report, essay, slide-like narrative, dashboard, marketing surface... reads better at a live URL'), guidance on honoring requested artifact form, a mandatory prerequisite ('Apply the governance skill before calling'), and a clear routing rule for the anonymous vs. account path. It also warns that binary assets must go through the Valet CLI instead.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further: it explains WHY it is destructive (it replaces the previous version's content for every reader), scopes the blast radius to the whole organization from the next read on, and discloses the dedupe behavior of repeat calls plus the Valet account requirement. That is real context beyond the structured flags.

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 action and input contract, then the override/dedup/auth caveats. Most sentences earn their place, though the first sentence is dense and the well-known-name examples could be trimmed 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 destructive, org-wide publish operation with no output schema, the description covers input contract, override semantics, discovery via list_skills, dedupe behavior, and auth requirements. An agent has everything needed to decide whether and how to call 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%, so baseline is 3, but the description adds meaning the schema cannot: the skill's name and description are derived from the SKILL.md frontmatter rather than passed as parameters. It does not elaborate further on org_name beyond what the schema already says.

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+resource ('Create or replace an organization skill') and immediately defines the input shape (SKILL.md plus supporting files). It is cleanly distinguishable from publish_agent, publish_app, publish_site, and from attach_skill/detach_skill, which the name alone could be confused with.

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 routes usage: publishing under a well-known name (governance, security, design-system) overrides Valet defaults org-wide, so do it 'when the user has asked to change how the organization works, and show them the content first'; publishing under a new name adds a skill that list_skills discovers by description. Both when-to-use and the sibling discovery path are named.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world. The description adds meaningful context beyond them: the tool 'changes nothing itself' and instead returns the Integrations page name and the `valet channels reauthorize` command. It also notes the account prerequisite, which the annotations don't cover.

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?

Core action is front-loaded in the first clause, followed by eligibility, mechanics, and prerequisites. Every sentence carries information, though the parenthetical credential-type list makes it slightly dense.

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

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

With no output schema, the description helpfully explains what the call returns (a pointer to the Integrations page and CLI command) and states prerequisites and refusal behavior. Complete for a read-only pointer tool, though it could note any rate or account-state constraints.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description adds no format, naming, or disambiguation detail for `channel` or `org_name`, so the baseline 3 applies.

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

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

The description states a precise verb and resource: renew the third-party authorization of a specific Slack or Telegram channel. It also implicitly distinguishes itself from reauthorize_connector by naming the channel context and the credential-bearing channel types. An agent can tell exactly what this operates on without opening the schema.

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

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

It gives clear eligibility conditions ('workspace access was revoked or bot scopes changed') and an explicit exclusion ('A channel with no credentials (cron, heartbeat, webhook, email, mcp) is refused'). It does not name a sibling alternative to route to, but the when-to-use context is concrete and complete.

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

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

Goes well beyond the annotations by disclosing what the call returns (an approval URL), that the connector's name and configuration are preserved with only new tokens issued, that each call mints a fresh link (consistent with idempotentHint=false), and that secret-based connectors are refused with a redirect to set_env_vars. It adds a real prerequisite (connecting a Valet account) that no annotation conveys.

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?

Dense and front-loaded: the qualifying conditions and the return value come first, and no sentence is filler. Some clauses are convoluted ("the address the person opens to approve it"), which slightly hurts scanability but not substance.

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 takes responsibility for describing the response shape (an approval address) and does so. Annotations cover the safety profile and the description covers prerequisites, refusal behavior, and side effects, leaving nothing an agent needs missing for this two-parameter 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 both org_name (including the fallback-to-default-org rule) and connector are already fully documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the 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?

States a specific verb (renew/reauthorize) plus the exact resource (an organization connector's authorization that runs in a browser) and narrows it to two qualifying cases: OAuth or Composio-managed connectors whose grant was revoked or whose initial authorization never completed. This distinguishes it cleanly from siblings like reauthorize_channel, attach_connector, or call_connector.

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 gives the when (provider-revoked grant, or a first authorization that never finished), the when-not (credentials stored as secrets are refused), and the alternative path for that case (use set_env_vars with the named secrets). It also states the prerequisite that a Valet account must be connected.

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

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

Annotations only flag destructiveHint=true; the description explains exactly what is destroyed and what replaces it: the site/app moves to a new URL, the old address stops serving it, and the old name becomes available to another service. It also discloses that agents keep their channels and have no address, plus auth and eligibility 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?

Front-loads the purpose, then layers behavior, restrictions, and prerequisites in a tight sequence without filler. It is dense but every clause carries information; the only mild cost is that the restriction list reads as a run-on.

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 mutation with no output schema and no annotations beyond the safety flags, the description covers the side effects, identity/eligibility constraints, and auth requirement an agent needs before invoking it. Nothing material is left implicit.

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 including the kind enum is already documented. The description's note about passing kind largely restates the schema text, and org_name is never addressed, so it adds only marginal value over structured data.

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 (rename) plus the three resources it operates on (website, app, agent), and no sibling tool competes for that purpose. An agent can distinguish it from destroy_service, publish_site, or share_service without opening any schema.

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

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

Gives concrete conditions: pass kind to disambiguate, a name holding another kind is refused rather than renamed, the architect agent cannot be renamed, and renaming an agent requires the org to have one. It also states the prerequisite of a connected Valet account. It stops short of naming a sibling alternative for edge cases, so not a full 5.

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

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

Adds real value beyond annotations: it discloses that in-flight requests are dropped, that a repeat restarts again (reinforcing idempotentHint=false), and, critically, that restarting removes nothing (consistent with destructiveHint=false). It also states the auth prerequisite (connecting a Valet account), which no annotation conveys.

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?

Five tight sentences that are front-loaded with the core action and scope, followed by behavioral consequences, verification guidance, refusal cases, and auth requirement. Every sentence carries distinct information with no 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 no output schema, the description covers the safety profile (removes nothing, drops in-flight requests), non-idempotency, target restrictions (websites refused), auth prerequisite, and the sibling to use for verification. Nothing an agent needs to invoke it 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%, so all four parameters are already documented, including the kind enum and process_type semantics. The description only echoes the process_type scoping ('or only those of one process type') without adding syntax or format beyond the schema, so the 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?

States a specific verb (restart) and resource (an app's/agent's running processes), plus the finer scope of a single process type. It implicitly distinguishes itself from siblings like get_service, destroy_service, and scale_service, and explicitly notes that websites are refused, so an agent knows which target classes are out of scope.

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?

Gives clear context: websites are refused, a Valet account connection is required, and get_service is named as the way to verify processes are up. It does not name a same-job alternative (there is effectively none for restart), so it stops just short of explicit when/when-not routing, but the preconditions and exclusions are well covered.

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

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

Beyond the destructive/idempotent annotations, the description discloses concrete consequences: scaling down stops running processes, scaling web to 0 takes the URL offline, a no-op when the count is unchanged, and the requirement to connect a Valet account. These are exactly the side effects an agent needs to warn about before a destructive call.

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 core action and per-kind rules are front-loaded, and every sentence carries a distinct constraint (range, safety confirmation, no-op, refusals). It is dense rather than padded, though it is long enough that a small amount of compression could tighten 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?

For a destructive, non-read-only mutation with no output schema, the description covers the safety profile, prerequisites (Valet account), per-kind parameter rules, and refusal conditions. Nothing an agent needs to call it 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 coverage is already 100%, so the baseline is 3. The description adds genuine value on top: the org-cap upper bound for app counts is not in the schema, it clarifies that process_type is app-only and omitted for agents, and that count is 0/1 for agents, reinforcing the enum-like meaning of kind.

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 ('Set how many processes of one type an app or agent runs') and immediately distinguishes the two target kinds (app vs agent) with different semantics. An agent can tell this apart from siblings like restart_service or destroy_service without opening a schema.

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

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

Explicitly covers when to use it, the confirmation requirement before scaling down, the valid 0/1 range for agents vs the org-capped range for apps, and hard exclusions: websites are refused, and changing an agent's model is not offered here. This routes the agent away from unsupported actions rather than leaving them to inference.

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

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

Goes well beyond the annotations: it explains that secrets are encrypted and never shown again, that an existing name is replaced (justifying the destructive hint), that the process only sees new values on its next start, that the answer names variables but never values, and that a Valet account is required. This is exactly the contextual disclosure annotations cannot carry.

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 action, and each sentence carries information. It is long and slightly repetitive around the secret/dashboard explanation, but almost no sentence 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?

With no output schema and a nested object parameter, the description still covers return shape ('names the variables set and never their values'), auth requirement, timing of effect, and the destructive replacement semantics. Nothing needed to call it 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks — notably that the 'vars' values pass through this conversation as a real cost, and that secret defaults to true while false yields dashboard-readable plain configuration.

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 ('Set environment variables on an app or agent') plus the input form ('as name to value'). An agent can immediately distinguish this from unset_env_vars and list_env_vars among its 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?

Gives real selection context: it says a value passed here travels through the conversation and suggests the user could instead enter it on the dashboard, which routes straight to Valet. It also explains the secret-vs-plain choice. It does not explicitly name sibling alternatives or exclusions, so it falls just 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.

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

Goes well beyond the annotations (destructive/not-readonly), disclosing replace-on-same-key behavior, that omitting pinned/expires_in clears them, size limits (4096 bytes content, 256 key), that over-limit writes are refused with remediation guidance, and an auth prerequisite (Valet account). The one soft spot is 'within a limit' for pinned memories, which is vague rather than quantified.

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?

Dense but front-loaded: write/replace semantics first, then recall and pinning, then limits, then safety rules, then auth. Every sentence carries distinct operational or safety content, and none is redundant 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?

No output schema, yet the description anticipates the failure mode (over-limit refusal naming how to make room) and the security surface (content is data, not instructions). For a destructive write tool with six parameters, this is complete enough to call correctly without opening anything else.

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), but the description still adds real semantics the schema does not: the omit-clears behavior for pinned/expires_in, the replacement-on-same-key contract, and concrete size ceilings. That is genuine value beyond structured fields rather than restatement.

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 (write) and resource (one durable memory for an agent under a key), and the replacement semantics immediately distinguish it from the sibling list_memories and destroy_memory. An agent can tell exactly what this tool does and what it is not for.

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 names the alternative ('list_memories first when you only mean to change one') and the condition that selects it, plus when not to use it ('never secrets or credentials') and when to pin sparingly. Nothing about route selection is left to inference.

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

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

Annotations already declare mutation/idempotency safety, and the description adds genuinely new behavioral context beyond them: the kind-mismatch refusal semantics, the server-side app-access prerequisite, the account connection requirement, and the exact nature and 72-byte limit of the visitor password. This is rich disclosure 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 tight paragraphs with the mode semantics front-loaded and edge cases second. Slightly repetitive against the schema's own mode descriptions, but no sentence is truly 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?

There is no output schema and annotations only cover the safety profile, yet the description fully equips the agent: what each mode does, the enum meanings, the kind-refusal rule, the app restriction, auth prerequisite, and password constraints. Nothing needed for a correct call 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 baseline is 3. The description adds some semantics the schema doesn't fully carry (visitor password is not a Valet credential, is handed to viewers, 72-byte cap), but much of its mode/password prose duplicates what the schema already states.

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 ('Set who can reach a website or app') and enumerates the three access modes it controls, so the agent immediately knows the domain. However, it never differentiates itself by name from adjacent siblings like share_site or publish_site, leaving that distinction to inference.

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?

Gives clear conditional guidance: the meaning of each mode, that kind should be passed to make mismatched names refuse rather than change, that apps require app access enabled on the server, and that a Valet account is required. It stops short of naming alternative tools (e.g. share_site) for cases the agent might confuse with this one.

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

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

Goes well beyond the annotations: it discloses the auth prerequisite (requires connecting a Valet account), that recipients need no Valet account, that anyone holding the email gains access and forwarding propagates it (the irreversible access-grant implicit in destructiveHint=true), and that re-sharing an existing address re-sends rather than duplicates. It also states the refusal condition for apps.

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?

Purpose is front-loaded and the paragraph reads efficiently, but the re-send rule and the sites-only restriction are restated from the input schema, so a couple of sentences do not fully earn their 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 7-parameter, non-read-only tool with no output schema, it covers the material concerns: auth requirement, access permanence, idempotency behavior, and the app-refusal error case. Only the response shape and any rate/error specifics are left unaddressed, which 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 every parameter including the email cap and the re-send behavior. The description mostly echoes that content and adds no syntax or format detail the schema lacks, so the baseline 3 applies.

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

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

The opening sentence names a specific verb and resource (share a website) and the mechanism (by email), with the scope constraint that sharing does not alter other visitors' access. It is clearly distinguishable from siblings like publish_site, set_service_access, and unshare_service without opening any schema.

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

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

It establishes clear context: use this to grant specific people email-based access, only for sites, resends the same link on repeat calls. It never names an alternative tool (e.g. publish_site for public access, unshare_service to revoke, set_service_access for broader access), so the agent must infer the boundary from sibling names alone.

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

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

Annotations already flag destructive and idempotent, but the description adds real behavior: a single restart when running, scoping to the service's own variables, refusal semantics with the reason surfaced, and the Valet account prerequisite. It does not explain whether the restart interrupts in-flight work.

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 side effect, then progressively layers the refusal rules. Slightly dense with several clauses, but each sentence carries non-redundant operational 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?

With no output schema, the description compensates by describing response behavior: refusals name the holder and what frees it, and unknown names are reported without failing. Combined with full schema coverage, an agent has everything needed to invoke and interpret the call.

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 name, names, and org_name. The description adds no per-parameter syntax or format detail, only an oblique note that inherited org variables are untouched. 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?

States a concrete verb (Remove) and resource (environment variables on an app or agent), plus the notable side effect of restarting the service. It is trivially distinguishable from set_env_vars and list_env_vars 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?

Gives explicit when-not conditions: variables referenced by a connector/channel or set by a resource are refused, and it names the actual alternatives (destroy_channel for an owned channel, detach_resource for resource variables). It also tells the agent that removing an unset name is non-fatal.

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

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

Annotations already declare destructive=true, idempotent=true, readOnly=false, but the description adds substantial context: links stop working immediately, revocation is permanent and cannot be undone, re-sharing mails a new link, missing shares are reported rather than refused, and it doesn't alter other users' access. This is rich behavioral detail beyond the structured hints.

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?

Core action is front-loaded and each sentence is informative, but there is minor redundancy ('revoking is permanent' and 'this cannot be undone' restate each other) and the sentence 'Sharing does not change who else can reach the site' is slightly confusing mid-definition.

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 correctly explains part of the return behavior (addresses with no share are reported) and covers permissions, limits, and failure modes. It is nearly complete, though it could say more about what the response contains for the revoked addresses.

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 adds meaning for the kind enum by explaining that app cannot be shared by email and will be refused, and clarifies the effect on the emails list (link stops working). This goes somewhat beyond the schema text.

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 (revoke) and resource (people's shares of a website, by email), which is unambiguous and clearly the inverse of the sibling share_service. An agent can identify the operation without opening the schema.

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

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

Gives a clear operating context: confirm the addresses with the user first, prerequisites (requires connecting a Valet account), and an exclusion (only a website can be shared by email; an app is refused). It never explicitly names the counterpart share_service, but the conditions for correct use are well covered.

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