Valet

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

Annotations already declare idempotentHint and non-destructive, but the description adds substantial context beyond them: re-attaching 'reports it and changes nothing', Slack requires a Slack app/browser and does not attach, apps cannot take organization channels, and a Valet account connection 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?

Front-loaded with the core action and effect, and nearly every sentence carries operational information. The Slack sentence is slightly convoluted ('gives the step to take and attaches nothing'), but it earns its place as an exception case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 prerequisites (Valet account connection), idempotency, special-case behavior (Slack, apps), and the sibling lookup tool. An agent has what it needs 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% and already documents all three parameters, including that channel comes from list_channels and org_name defaults to the first-joined organization. The description adds little parameter-specific detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Attach an existing organization channel to an agent') plus the effect ('so the channel's events wake it'). It is clearly distinct from siblings like create_channel, detach_channel, and list_channels, which it references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: use list_channels to find the channel, use create_channel for apps (which take no organization channels), and recognizes that Slack is a special case where nothing is attached. It gives concrete when-to-use and when-not-to-use guidance.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Goes well beyond the annotations, which only declare readOnlyHint=false, idempotentHint=true and destructiveHint=false. The description discloses that version pins are ignored, that org skills must be published, the built-in fallback behavior, catalog copy/install/reuse semantics, refusal cases, and that the agent is rebuilt so the change takes effect.

Agents need to know what a tool does to the 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 correctly front-loaded in the first sentence, but the body is dense run-on prose and repeats the latest-version/@v2-ignored rule that the schema already states. Every clause carries substance, yet the length is higher than needed for a three-parameter 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?

For a complex, no-output-schema mutation tool, the description covers prerequisites, edge cases, refusal outcomes, idempotent behavior, and account requirements. Nothing an agent needs to invoke this 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 schema already documents each parameter and the @v<N> pin. The description nonetheless adds meaning by explaining what org:, bare, and catalog: prefixes do at runtime (install a copy, reuse an existing copy, refuse name collisions), which is 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 and resource ('Attach a skill to an agent so the agent can use it') and adds the key scope constraint 'Skills attach to agents only,' which separates it from attach_channel, attach_connector, and attach_resource. An agent knows 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?

Gives clear routing context for the argument forms (org:/bare name vs catalog:<name>) and the prerequisite chain (create_service with kind skill, then publish_skill, or a built-in). It does not, however, explicitly compare itself to sibling tools like attach_resource or detach_skill, so selection against alternatives is left implicit.

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?

With annotations already declaring non-destructive, idempotent and open-world, the description adds substantial non-obvious behavior: signature verification before delivery, X-Valet-Visitor and delivery_key headers, 2xx-else-retry-for-a-day, refusal of webhooks lacking secret_name, and the fact that the secret is never returned. These are operational facts an agent cannot infer from the 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?

Front-loaded with purpose, then types, then delivery semantics, then failure modes — a sensible ordering with no filler sentences. It is a dense single paragraph, however, and the delivery/verification details could be split or bulleted to be scanned faster.

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

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

Covers creation, idempotency, refusal modes, runtime delivery behavior and setup prerequisites for a 9-parameter mutating tool with no output schema. The only soft gap is what a successful call returns (channel record? delivery URL?), which is left implicit aside from the 'reports it' case for duplicates.

Complex tools with many parameters or behaviors need more documentation. 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 real meaning: it explains why secret_name exists (the tool never returns a secret), that an unsignable case exists but verification cannot be disabled, and ties channel_kind to list_catalog_channels. It stops short of documenting per-kind required combinations in one place, so it's a notch below the top.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Create a channel on an agent or an app') and immediately decomposes the two target types into their allowed channel kinds. An agent can distinguish this from sibling operations like attach_channel or reauthorize_channel 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 states prerequisites (connect a Valet account, set the signing secret with set_env_vars before passing secret_name, get channel_kind from list_catalog_channels) and gives the alternative path when a channel already exists with different settings ('destroy it first'). Also carves out Slack/Telegram as not-creatable here, which is an exclusion, not just 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 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 only say it is a non-read-only, non-idempotent, non-destructive, closed-world call; the description goes far beyond that by disclosing the one-hour writable window, credential-bearing URL, expiry, no-force-push, no-sharing/logging warning, ten-open-push cap, file/size limits that cause refusal, ownership rule, and Valet account requirement. This is exactly the extra behavioral context 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?

It is a single dense paragraph, but the core action is front-loaded and the later clauses (result contents, limits, publish step, credential warning) each carry distinct information. A few clauses could be split for readability, yet no sentence 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 fully compensates by enumerating the result payload (Git URL with credential, push id, branch, starting commit, commit name/email, two filled-in recipes) plus limits, ownership and account requirements. An agent has everything needed to invoke it and use 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, org_name and idempotency_key are already documented in the schema (including the retry-safety semantics of the key). The description adds only the 'must exist' precondition for name and does not extend parameter meaning further, 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 (open a Git push) and scopes it precisely to an existing website/app/agent/skill, with the branch/one-hour/credential nature made explicit. It is instantly distinguishable from create_service (which creates the service) and publish_* (which consume the push).

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('when you can run git with network access'), when-not ('Otherwise publish with files'), prerequisites ('The service must exist first: create_service makes it'), and the follow-up call (publish_site/publish_app/publish_agent/publish_skill with push:{id, commit}). Nothing about the workflow 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 only declare the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds substantial context beyond that: name collisions and per-kind org limits are refused, unpublishing state ('nothing reaches an agent until it is published'), skill URL privacy, catalog install returning the prior copy, and the Valet-account connection 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?

Front-loaded and information-dense, but markedly wordy and repetitive: the four-kind enumeration recurs several times and the skill/catalog paragraph restates points already implied earlier. Every sentence is relevant, yet the volume is greater than the operation warrants.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 tells the agent what comes back (organization, kind, name, URL) and what to do next (publish to that name). Auth prerequisites, refusal conditions, and the skill/catalog lifecycle are all covered.

Complex tools with many parameters or behaviors need more documentation. 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 on top: kind semantics mapped to create targets, the omit-name fallback and its skill exception, and especially catalog behavior (install Valet's curated skill under name, published as the organization's first version, previously-installed orgs get their copy back).

Input schemas describe structure but not intent. Descriptions should explain 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 and states the precise scope: creating an empty website, app, agent, or skill before publishing. It explicitly separates itself from the publish_* siblings by noting they 'change a service that exists and refuse a name that does not.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing rules: this is the first step for anything new; publish_site/publish_app/publish_agent/publish_skill operate on existing services. It also names the condition for kind=skill (sharing know-how with a team) and the catalog variant.

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/idempotent) by stating irreversibility, requiring user confirmation, disclosing refusal conditions and the follow-up call, the idempotent-soft-delete behavior, the Slack integration exception, and the Valet-account connection 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?

Front-loads the core action and irreversibility warning before the branching detail. It is fairly long and dense with repeated scope-switching, but nearly every sentence carries operational instruction rather than 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, but the description explains what happens on refusal and success ('the answer names each holder', 'changes nothing'), covers the app and Slack special cases, and states the auth prerequisite. 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 baseline is 3, but the description adds genuine meaning: it explains that omitting name targets an org channel while supplying it targets an agent/app-owned channel, and that org_name defaults to the first-joined org. This scoping semantics is hard to infer from the schema strings alone.

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

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

A specific verb and resource ('Destroy a channel and its routes') with immediate scope clarification. It distinguishes itself from detach_channel, list_channels, and create_channel by explaining the ownership/scope branching that separates destroy from detach.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 and when-not: without name destroys an org channel (refused if held by an agent), with name destroys an owned channel, and detachment is the correct alternative when the agent only holds the channel. It also names the confirm-with-user prerequisite and the follow-up call when refused.

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 adds real value beyond them: what destruction concretely causes (Valet stops sending release files to the checker's URL), the user-confirmation requirement, the policy-reference refusal and its error payload, and the auth prerequisite ('Requires connecting a Valet account'). Only the 'already gone changes nothing' sentence largely restates idempotentHint.

Agents need to know what a tool does to the 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 direct effect, then layered with confirmation, refusal handling, idempotency, and auth. Six sentences is a bit long, and the idempotency sentence overlaps with the annotation, but each other sentence carries distinct 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?

No output schema exists, and the description compensates by covering the side effect, the refusal/error behavior with named policies, the user-confirmation requirement, and the account prerequisite. An agent has everything needed to call this destructive tool safely and 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 both parameters (checker with its org:snyk or bare-name format, and optional org_name with its default) are already fully documented. The description's lone contribution is 'by name', which adds nothing 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 (destroy), resource (checker), and ownership scope (an organization's own checkers) by name. This clearly separates it from sibling destroy_* tools such as destroy_policy and destroy_resource, which target different resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructs to confirm with the user first, and explains the refusal case with its remedy: a checker named by a release policy is refused, so destroy_policy first or repoint with set_policy. It also carves out the no-op case for an already-deleted checker, so the agent knows when this call is pointless.

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/idempotentHint, but the description adds substantial value beyond them: irreversibility, the refusal behavior for held connectors and the fact that the response names each holder, the agent-owned-connector case, no-op behavior when already gone, and the Valet account auth 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?

Four sentences, all front-loaded with the destructive warning first, and each sentence carries actionable information (irreversibility, remedy via detach_connector, idempotency, auth). Dense but no filler; slightly long but justified for a 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?

There is no output schema, and the description compensates by describing what the answer contains in the refusal cases. Combined with annotations and full schema coverage, an agent has everything needed to call this 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% and the schema already documents both org_name (default org behavior) and connector. The description only implies the org scope implicitly and adds no syntax, format, or naming guidance beyond the schema, so baseline 3 applies.

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

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

States a specific destructive verb ('Destroy') on a specific resource ('organization connector') plus the side effect ('its stored credential'). It also implicitly distinguishes itself from detach_connector and from destroying an agent-owned connector, so the agent can tell it apart from many siblings in the 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?

Explicit when-to-use guidance: confirm with the user first because it is irreversible, and use detach_connector to free holders before destroying. It also names the preconditions (holder must be freed) and the alternative path when an agent owns the connector.

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?

Annotations already flag destructiveHint=true and idempotentHint=true, yet the description adds substantial beyond-annotation detail: destruction cancels running policy evaluations and unblocks waiting releases, decided evaluations are untouched, deleting an already-absent policy is a no-op, and the Valet account prerequisite. This is unusually rich behavioral disclosure for 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?

Purpose is front-loaded and the safety instruction is present, but the paragraph runs six sentences and drifts into change/enforcement semantics that pertain more to set_policy than to destroy. Slightly long, though still information-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?

For a 2-parameter destructive tool with full schema coverage, annotations, and no output schema, the description covers effects, idempotency, and auth. The one gap is that it never states the policy definition itself is permanently lost — it emphasizes what survives (past evaluations) rather than what is irrevocably destroyed.

Complex tools with many parameters or behaviors need more documentation. 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 reinforces 'by name' for the policy parameter but adds no format, uniqueness, or lookup semantics beyond that — 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 gives a specific verb and resource with scope ('Destroy one of an organization's release policies by name'), and the use of 'destroy' plus 'by name' cleanly separates it from list_policies and set_policy among the siblings.

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

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

It supplies concrete decision-relevant context: 'Confirm with the user first' and 'Requires connecting a Valet account,' plus the warning that removal cancels running evaluations. It stops short of naming a sibling alternative (e.g., use set_policy to modify instead of destroying), so no explicit when-not 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 already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds substantial context beyond them: irreversibility, the refusal condition for app-attached resources, that the error response names the offending apps, that removal happens asynchronously in the provider, and that destroying an already-removing resource is a silent no-op. It also discloses the auth prerequisite ('Requires connecting a Valet account').

Agents need to know what a tool does to the 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 destructive action and the confirmation requirement before any edge cases. Every sentence carries operational information, though the idempotency sentence partially restates the idempotentHint annotation and the auth note reads as a trailing addendum, so it is dense rather than perfectly trimmed.

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

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

For a two-parameter destructive tool with no output schema, the description covers everything an agent needs: what is destroyed, confirmation requirement, the refusal/error shape (app names), the required remediation tool, async semantics, repeat-call behavior, and auth. 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 the schema already documents both `org_name` (including the omit-to-use-default behavior) and the required `resource` name. The description adds no parameter-level 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?

The description opens with a specific verb+resource ('Destroy a resource and all of its data') and immediately scopes what 'all its data' means ('every table and row in a database'). This distinguishes it from the many sibling destroy_* tools (destroy_channel, destroy_service, destroy_connector, destroy_memory) 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?

It states when to use it (resource destruction), an explicit prerequisite ('confirm with the user first'), and a concrete alternative flow when the precondition fails: if the resource is attached to an app the call is refused and the agent should use detach_resource first, then retry. That is when/when-not/alternative all in one place.

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 destructiveHint=true and idempotentHint=true, but the description goes far beyond them: it discloses per-kind fallout (resources detached and kept, app releases/source removed), what survives (agent sessions/memories), that a well-known skill name restores Valet defaults org-wide, and that a missing name answers harmlessly. This is exactly the 'what gets destroyed vs. preserved' context a destructive tool needs.

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

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

Front-loaded with the destructive warning and kind guidance before the per-kind details, and the identification rules are saved for last. It is long, but the four-kind complexity justifies most of the length; a few clauses 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 covers return-relevant behavior ('the answer names them for destroy_resource', 'answers that nothing was destroyed') and all four kinds, org scoping, and both identifier paths. An agent can invoke this correctly without opening another tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: it explains that kind causes a name of another kind to be refused rather than destroyed, and that site_token lets whoever published anonymously always take the site down — behavioral meaning the schema fields only hint at.

Input schemas describe structure but not intent. Descriptions should explain 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, agent, or skill.' The four kinds are enumerated, immediately distinguishing it from sibling destroyers (destroy_channel, destroy_resource, destroy_session, destroy_connector) and from create/publish counterparts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 prerequisites and ordering: call destroy_session and destroy_memory first for agent cleanup, and detach_skill frees a skill-blocked refusal. It names the alternatives (destroy_resource, detach_skill) and the hard exclusion ('The architect agent cannot be destroyed'), leaving little 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 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?

Annotations only supply destructive/idempotent flags; the description adds substantive behavior: the connector survives in the organization, callers start erroring (intended outcome), a running agent gets a scheduled restart, and non-agent detach attempts are refused rather than silently no-op. It also discloses the auth prerequisite ('Requires connecting a Valet account'). This is well beyond what structured fields convey.

Agents need to know what a tool does to the 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 key distinction from destroy_connector are front-loaded in the first sentence, and the second paragraph covers consequences and refusal cases in a logical order. It is on the long side and includes filler like 'which is the intended outcome,' but almost every clause carries real behavioral 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 must carry the return/effect story, and it does: callers begin erroring, agents restart on schedule, and invalid target types are refused. Combined with the auth requirement and the survival of the connector record, an agent has everything needed to invoke this destructive, idempotent operation 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 each of the three parameters is already documented with required/optional status and fallback semantics for org_name. The description contributes only an indirect hint about name matching ('a misspelled name is never read as a grant taken back') and no format, casing, or scoping 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 ('Detach a connector from a website or agent') and immediately scopes it against the sibling that created the state ('ending the grant attach_connector made'). It further distinguishes itself from destroy_connector by noting 'The connector itself stays in the organization.' An agent can select this over its many siblings 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 a clear motivating condition ('everyone who can open the page can call every tool it exposes... detaching is the way to end that reach'), which tells the agent when this tool is the right one. It also names invalid targets (an app cannot hold a connector, so it is refused). It never explicitly names destroy_connector as the alternative when removal rather than revocation is wanted, so it stops short of full when/when-not 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?

The description goes well beyond the annotations: it explains that env vars are removed, a restart is requested, the running process keeps the vars until replaced, non-matching variable values are left in place, resource data is preserved, other apps retain the resource, and a Valet account is required. It is consistent with idempotentHint=true ('changes nothing') and destructiveHint=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?

The purpose is front-loaded, but the body is long and at least one sentence is garbled ('detaching while Valet still owes the restart or the removal, which it keeps trying; the answer gives the reason'), which costs clarity. Several clauses 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 carries the return-value burden and does so partially ('the answer gives the reason', 'the answer names it'), plus it discloses auth requirements and edge cases. The awkward phrasing leaves some return behavior ambiguous, preventing a 5.

Complex tools with many parameters or behaviors need more documentation. 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, org_name and resource are already documented in the schema. The description adds no syntax, format, or constraint detail 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 ('Detach a resource from an app') and immediately distinguishes it from the destructive sibling by noting 'The resource itself and its data are unchanged.' An agent can tell this apart from destroy_resource 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?

Usage is implied through behavioral edge cases (detaching a non-attached resource is a no-op, other apps holding the resource keep it), but there is no explicit when-to-use framing and no alternative named (e.g. destroy_resource to delete the resource itself, attach_resource to re-attach). The agent must infer the 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?

Annotations already declare destructiveHint=false... destructiveHint=true and idempotentHint=true, but the description adds genuinely useful context beyond them: what survives (the org copy), that the agent is rebuilt, the no-op idempotency consequence, and the Valet-account auth requirement. It does not describe rebuild downtime or any response, but the added 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?

Front-loaded with the core action, then layering scope, edge cases, and auth in short sentences that mostly earn their place. Slightly repetitive around the organization/catalog copy but no wasted 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?

For a mutation tool with annotations present and no output schema, the description covers the key behaviors an agent needs: reversibility, idempotency, and auth. It leaves out any note on the rebuilt agent's state or timing, 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 coverage is 100%, so the baseline is 3, and the description adds meaning for the 'skill' parameter by explaining the built-in case ('Give a built-in's name to detach Valet's default of it'). The org_name fallback is covered in the schema rather than the description, keeping it just above 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 ('Detach a skill from an agent') and immediately clarifies the scope ('the skill stays in the organization'), which cleanly distinguishes it from the sibling attach_skill. An agent can tell what this does and what it does not delete 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?

Explains the operational context well: the skill persists for other agents, built-in names behave specially, and detaching an unattached skill is a no-op. It does not explicitly name attach_skill as the inverse alternative, so it stops just short of full when/when-not 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 already declare readOnly/idempotent/non-destructive, and the description adds genuine semantics on top: matching is word-based against name and description, results are capped at five and include the sentence saying when each applies, and an empty answer means no word match rather than an empty catalog. The auth prerequisite (Valet account connection) 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?

Front-loaded with the action and the when-to-call rule, and every sentence carries operational information. It is slightly dense and repeats the call instruction across two paragraphs, but no sentence is 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 two-parameter search tool with no output schema, the description covers invocation timing, matching behavior, result count, result shape (best matches plus applicability sentence), empty-result meaning, and the account prerequisite. Nothing an agent needs to call or interpret 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% and already documents both parameters, including the org_name fallback behavior. The description reinforces what kind of words to pass ("words from the task") and that matching is lexical, but adds no format, tokenization, or ranking detail beyond the schema — the baseline 3 for fully covered schemas.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Search the organization's skills") and immediately clarifies what a skill is ("its playbooks for how it does things"). It also distinguishes itself from the two nearest siblings by name: get_skill for reading a match, list_skills for the full inventory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 invocation conditions: at the start of any task the organization may have a way of doing, with words from the task, and whenever the user names a skill the client lacks (with a concrete example, "use the duck skill"). It also names the follow-up action (get_skill) and the escape hatch when results are empty (list_skills).

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 declare this a safe, idempotent, non-open read, and the description adds a large amount beyond that: the full phase lifecycle, the meaning of superseded/checking/refused/starting/crashed, the trap that a working URL does not prove the new release is live, and that state_reason and failure_excerpt explain failures. That is exactly the operational context 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?

Content is front-loaded with return values and then polling and state semantics, which is the right order, and with no output schema the detail earns its place. However the opening sentence is an extremely long run-on with a giant embedded parenthetical of phase names, making it hard to parse at a glance; tighter sentence breaks would preserve the same information more legibly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 no structured state documentation, so the description must carry the return semantics entirely, and it does: states, phases, log behavior, deploy_state values, and the fields that explain failures. An agent has everything needed to poll correctly, interpret terminal states, and decide what to do next.

Complex tools with many parameters or behaviors need more documentation. 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 both parameters are already documented, including the default-org behavior for org_name. The description only implies build_id comes from publish_app, which the schema already states, so there is no added parameter meaning beyond 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 resource (the build that publish_app started) and enumerates exactly what is returned: state, phase, logs, and, on success, release, URL, and deploy state. It explicitly ties itself to the publish_app sibling and to get_evaluation for the checking path, so an agent can distinguish it from get_logs, get_service, or get_evaluation 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 when/when-not guidance: poll every 10-15 seconds until deploy_state is up, crashed, or refused, or the build failed or was superseded, with the expectation that most deploys finish within five minutes. It routes to named alternatives for specific sub-cases (get_evaluation with wait_seconds 20 for checking, follow the newer build after superseded) rather than leaving the agent to guess.

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, closed-world), and the description adds genuinely new behavioral context: monitor findings never block while other findings do, that a passed evaluation's release goes live shortly after and a blocked/errored one is refused, the polling loop via retry_after_seconds, and the auth requirement. This is well beyond what the structured fields convey.

Agents need to know what a tool does to the 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 return contents are front-loaded, then usage guidance, then the auth note. It is dense and a little sprawling in the middle enumeration, but nearly every clause carries distinct information an agent needs (blocking vs monitor findings, the poll loop).

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 return values and does so thoroughly, listing each field family and the fix guidance. It also covers the async/polling lifecycle and the account prerequisite, leaving nothing an agent needs in order to call and interpret 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 all four parameters are already documented, including the 'use 20 while retry_after_seconds' note on wait_seconds and the 'omit for latest' note on evaluation_id. The description restates the evaluation_id and wait_seconds semantics rather than adding format or syntax detail 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 (follow/read) and resource (a publish's release evaluation) and enumerates exactly what the answer contains: status, per-policy evaluation with checker/enforcement/status, blocking findings with file/line/package, rule and fix, monitor findings, and deploy outcome. This is far more specific than the sibling get_build or list_releases, so an agent can tell it apart 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 clear operating conditions: omit evaluation_id to read the service's latest evaluation, and re-call with wait_seconds 20 while the answer carries retry_after_seconds. It also states the prerequisite that a Valet account must be connected. It stops short of naming a sibling alternative (e.g. list_releases) for the when-not case, so it is strong context rather than a full 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context on top: it searches only the newest 1000 buffered lines so older lines can be evicted, it flags 'truncated' when it cuts off or older lines may exist, attributes with credential-like names are dropped while message text is returned verbatim, and a Valet account connection is required. That is unusually rich disclosure beyond the structured safety 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?

The definition is front-loaded with the verb, resource, and return shape, and every clause carries usable information (buffer window, truncation flag, redaction policy, refusal of websites). It is a single dense paragraph with stacked clauses, which is slightly harder to scan than it needs to be, but there is little genuine waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, yet the description fully specifies the return shape (time, source, process, level, message, structured attributes, plus a truncated marker) and the source semantics (app/agent for service output, valet for control-plane lines). Combined with annotations covering the safety profile and a fully documented schema, 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 description coverage is 100%, so the schema already documents every parameter, including enum, defaults, and max values for kind, since, and limit. The description largely restates those bounds ('default 15m, at most 24h'; 'default 200, at most 1000') and adds only the qualifier that limit returns the newest matching lines, 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+resource ('Read an app's or agent's recent log lines') and immediately enumerates the returned fields (time, source, process, level, message, attributes). It also declares scope and ordering ('oldest first'), which no sibling tool shares, so the agent can distinguish it from get_build, get_service, or get_session 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 concrete context for use: it reads the buffered window and 'never follows' (ruling out tailing), a website is refused, and narrowing is done via since/process/limit with stated defaults and caps. It does not name any alternative tool, but no sibling competes for this purpose, so the guidance is effectively complete without 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 declare read-only/idempotent/non-destructive, and the description adds real context on top: the per-kind return shape, that other kinds' fields are absent, the enumerated access modes, and the important security guarantee that a gated service reports gating but never the visitor password.

Agents need to know what a tool does to the 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 and identification rules, then enumerates return fields per kind. The enumeration is long but each sentence carries distinct information; the structure is sound even if 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?

There is no output schema, so the description must carry return-value semantics, and it does so thoroughly per service kind plus shared behaviors like draft state and recipient listing. An agent knows what to expect after 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 coverage is 100% and the schema already documents name, org_name, and site_token including the account requirement and the org default. The description largely restates that, adding only the 'published anonymously' framing for site_token, so baseline 3 applies.

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

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

Opens with a specific verb and resource set: 'Get one website, app, agent, or skill by name.' That clearly separates it from list_services (many), create_service, and the kind-specific get_skill/get_connector siblings.

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

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

Explains the two identification paths and their preconditions: name requires a connected Valet account, site_token covers anonymously published sites. It does not address when to prefer this over the overlapping get_skill or get_connector siblings, which is the main missing piece.

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?

With readOnly/idempotent/non-destructive annotations already covering safety, the description adds substantial behavior: org-vs-default source resolution, version propagation to publish_skill as base_version, the one-hour expiring read-only Git URL that 'cannot push' and should not be shared or logged, and per-call limits (50 files, 192 KiB text, 128 KiB file). It also discloses binary files are listed but not returned and where to install the result.

Agents need to know what a tool does to the 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 and the governance-before-work rule, and every sentence carries operational information. It is nonetheless long and dense across five paragraphs, mixing resolution logic, file limits, install paths, and git into a stream that could be organized more tightly, so not a full 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?

For a 7-parameter tool with no output schema, the description covers source provenance, versioning, file listing/limits, install destination, git workflow, anonymous mode, and the org-vs-default distinction. 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 coverage is 100%, so baseline is 3, but the description adds real semantic value beyond the schema: parameter interaction rules ('release... works with path and all_files', 'git cannot be combined with path, release, or all_files'), the all_files size-limit refusal behavior, and the org_name default (account's first-joined org). This goes well beyond restating field definitions.

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

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

States a specific verb and resource ('Read one of the organization's skills') and immediately clarifies the concept with 'its playbook for a kind of task'. It also distinguishes itself from siblings by noting 'find_skill and list_skills say which skills exist', so an agent can tell discovery apart from reading without inspecting 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 and prescriptive: 'Read a skill before starting any task its description covers... and whenever the user names it', plus 'Call it with governance before any work and again before any publish'. It names the alternative tools (find_skill, list_skills) and the exact cases that select them, leaving little 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?

Beyond the readOnly/idempotent/non-destructive annotations, it discloses binary files are listed but not returned, that republishing a release's files rolls back, that the git URL expires in an hour and cannot push, that it must not be shared or logged, that git cannot be combined with path, and that a Valet account is required. This is unusually rich behavioral context.

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

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

The core behavior (list files vs read one file) is front-loaded before the release, rollback, binary, and git notes. It is dense with useful constraints rather than filler, though ten sentences is on the long side and the git guidance 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 carries the return-value burden and does so: it states that without path it lists files, with path it returns one file's text, binary files are withheld, and git returns a URL plus clone commands. 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 the baseline is 3, but the description adds real meaning beyond the schema: release controls reading an earlier release and carries rollback semantics, path switches between listing and fetching, and git's expiry and path-exclusion constraint are restated in prose. org_name is left entirely to the schema, which keeps this from 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 states a concrete verb and resource: reading the published files of a website, app, agent, or skill's active release, with the list-vs-single-file distinction spelled out. This clearly separates it from sibling read tools like get_build or list_releases and from the publish_* family.

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

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

It explicitly says when to use it ('Read before you change something someone else built, so your publish carries their work forward') and when to use the alternative ('Pass git: true instead... Prefer it to reading files one at a time'). It also names list_releases as the source of the release value, so routing is unambiguous.

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 this as read-only, idempotent, non-destructive, and closed-world, so the description does not need to restate safety. It adds useful behavioral context beyond annotations: ordering of built-ins before catalog entries, exclusion rules, setup-completion information per entry, and the Valet account prerequisite.

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

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

The description is front-loaded with the purpose and is composed of dense but useful sentences. Every sentence contributes scope, exclusions, ordering, setup behavior, or prerequisites, though it is longer than strictly necessary for a simple list operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 appropriately explains the contents and meaning of returned entries, including built-in kinds, catalog entries, exclusions, and whether setup can be completed automatically. It does not specify exact response fields, but it covers enough for an agent to select and interpret the tool correctly.

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

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

There is only one parameter, org_name, and schema description coverage is 100%, so the schema already explains its meaning and default behavior. The description adds no parameter-specific syntax or constraints beyond the account prerequisite, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: it lists channel kinds an agent can have, including built-in and catalog kinds. It clearly scopes the result by naming built-ins, catalog entries, exclusions, and the setup information returned, which distinguishes it from a plain list_channels operation.

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

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

The description gives clear context for use by explaining what kinds are included and excluded, mentioning create_channel, and noting that a Valet account connection is required. It stops short of explicitly saying when to choose this over list_channels or list_catalog_connectors, but the catalog-discovery purpose 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 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 read-only, idempotent, non-destructive semantics, but the description adds real value beyond them: it requires a connected Valet account, it explicitly guarantees no webhook secret is ever returned, and it explains what a "degraded" channel means. It does not discuss pagination or result limits, which would matter for a list operation.

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

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

The mode logic is front-loaded immediately after the opening sentence, which is the right ordering. The return-field enumeration is dense and delivered as one long run-on paragraph, but with no output schema present each of those details earns its place.

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

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

With no output schema, the description takes on the burden of describing return shape and does so thoroughly: row fields, webhook/mcp URL, app delivery path, last five delivery states, and the degraded condition. Auth prerequisite and the secret-exclusion guarantee round out what 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%, so both parameters are already documented; the description reinforces the dual role of name (agent or app) but adds nothing about the syntax of a name. org_name is never mentioned in the description at all, leaving the schema to carry it — 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 channels") and then defines three distinct scopes keyed on the name argument: organization channels, an agent's channels, an app's channels. The scope is unambiguous, but it never names the closest sibling (list_catalog_channels) or explains how this differs from it, even though it mentions whether a channel "came from the catalog".

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 three-mode breakdown (omit name, pass an agent's name, pass an app's name) is effectively when-to-use guidance, and "how to find a channel to attach" gives a concrete scenario. It stops short of naming alternatives or stating when not to call it, so it's clear context rather than full 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?

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?

Beyond the readOnly/idempotent/closed-world annotations, it discloses security behavior ('A secret setting shows as (set), never its value'), the semantics of blocking vs monitor enforcement, the 30-day evaluation window, and an authentication prerequisite ('Requires connecting a Valet account'). These are exactly the operational facts an agent cannot derive 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?

Purpose is front-loaded in the first sentence, and every sentence carries content — the return-shape detail matters because there is no output schema. Some sentences are densely packed (the checker fields and the policy fields in one clause each), which costs a little readability but no sentence is 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 enumerating what each policy and checker returns, and it covers the auth requirement, the evaluation window, and enforcement semantics. Nothing needed to call a one-parameter read-only listing 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?

There is a single optional parameter with 100% schema description coverage, and the schema already explains the omit-to-use-default behavior, so the description adds nothing about org_name. Per the rubric this is the baseline 3 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?

The description names a specific verb and resource ('List the release policies that evaluate every publish of an organization') and scopes it precisely to what the listing contains, including the two checker sources. An agent can distinguish this from set_policy, destroy_policy, and set_checker 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 gives a clear when-to-use trigger ('Call it before publishing to see what will be evaluated, and fix what you can first') and explains the blocking vs monitor distinction that governs what the agent should do with the results. It references set_checker as the tool that adds organization checkers, but never states an explicit alternative-selection rule such as when to prefer get_evaluation or a single-policy read.

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, and the description adds meaningful behavioral detail: releases are newest first, never-live releases are omitted, websites are refused, and a Valet account is required. It also previews the returned fields, which is especially valuable because there is no output 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 definition is front-loaded with the core purpose and return shape, and most sentences carry useful constraints. The rollback and skill-version sentences are slightly workflow-oriented for a list tool, but they remain relevant and do not bury the main action.

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

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

With no output schema, the description needs to explain return content, and it does so by naming version, state, commit, creation time, and active release. It also covers filtering behavior and prerequisites, making it complete enough for an agent to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents name, limit, and org_name. The description reinforces ordering and scope but does not add parameter-level syntax or edge-case detail beyond what the schema provides, making the baseline 3 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 gives a precise verb and resource: list an app's, agent's, or skill's releases, and it specifies the returned fields and ordering. It also distinguishes the action from related tools like get_source and get_skill, which are described for different read/rollback purposes.

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

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

It provides clear context: use it to inspect release history, then use get_source for rollback files or get_skill for a skill's release version. It also states exclusions and prerequisites, including that websites are refused and a Valet account connection is required. It does not explicitly state a full when-to-use rule against every alternative, so it falls short of a 5.

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

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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real value: an authentication prerequisite ('Requires connecting a Valet account') and a security-relevant exclusion ('never returns a variable value'), plus the attachment states that can appear.

Agents need to know what a tool does to the 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 verb, resource, and ordering; the two short trailing sentences carry the usage cases and the auth/exclusion notes. The middle enumerations of fields and attachment states are dense but each earns its place by describing returns in the absence of an output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 usefully enumerates what comes back and explicitly rules out variable values, and it states the auth requirement. It omits pagination or result-count limits, which is the main remaining gap for a list tool.

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

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

One parameter with 100% schema description coverage, so the schema fully documents org_name including the omit-default behavior. The description only implies org scoping and adds no syntax or format detail, so baseline 3 applies.

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

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

States a specific verb and resource ('List the organization's resources'), gives ordering ('newest first'), and enumerates the returned fields (name, provider, plan, state, attachments). The org-scoping distinguishes it from the catalog sibling, so an agent can tell it apart from list_catalog_resources.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 usage contexts: finding a resource to attach by name, or one no app holds before deleting it. It does not name the alternative tool (list_catalog_resources) or state when NOT to use it, so it is clear but not fully 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds context the annotations cannot: it requires a connected Valet account, and it discloses a listing omission rule (built-in skills absent until the org makes its own). It does not mention pagination or result limits.

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

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

Purpose and scope are front-loaded in the first sentence, with routing, auth, and omission caveats following in logical order. Five sentences is slightly long and 'Each row says its access mode' is mildly redundant with the opening field list, but nothing 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?

There is no output schema, yet the description enumerates the returned fields (kind, URL, access mode, last published) and states the auth prerequisite and the sibling boundary. That is everything an agent 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%, and the schema fully documents both kind (with enum) and org_name including the default org behavior. The description's 'Pass kind to narrow to one kind' only restates the schema, adding no syntax or edge-case detail beyond it.

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

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

Opens with a specific verb and an exhaustive resource list ('every website, app, agent, and skill') and states the returned fields. It explicitly distinguishes itself from list_skills by explaining that built-in skills are excluded until the org creates its own, so an agent can tell the two list tools apart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 when-to-use rule ('the first read when the user names something and you do not know what it is') plus a recovery scenario for names lost from conversation. It also names the alternative (list_skills) and the condition that selects it.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: it returns names and descriptions only (not content), it lists well-known names plus every org-authored or catalog-installed skill, and it requires a connected Valet account. The one repetition about Valet work/governance dilutes slightly but the added context is real.

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

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

Action and trigger are front-loaded in the first sentence, and the second paragraph usefully describes the return rows. However, the 'Valet work or not' clause and the later 'governance skill also tells you to call this before Valet work' sentence repeat the same point, and a stray unmatched quote around 'use the duck skill' is a minor blemish.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 row contents (name plus the applicability-sentence description) and the read-vs-list split from get_skill, and it flags the account prerequisite. The only real gap is it says nothing about ordering, volume, or truncation for large skill sets, which matters for a list tool.

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

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

Only one optional parameter, and the schema already documents it at 100% coverage including the default-org behavior. The description never mentions org_name or the multi-org fallback, so it adds nothing beyond the schema. Baseline 3 applies 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 organization's skills') and immediately defines what a skill is ('playbooks for how it does things'). It also clearly delineates the boundary against get_skill (reads content) and find_skill (keyword search), so an agent can distinguish it from siblings 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?

Explicit triggers are given: when a task might be covered by org practice, and whenever the user names an unknown skill. It also names the follow-up ('read a matching skill with get_skill before starting') and the alternative ('To search by words from the task instead, call find_skill'). This is textbook when/when-not/alternative 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 already declare destructiveHint=true and openWorldHint=true, but the description goes well beyond them: it discloses that publishing REPLACES the agent's source, that a deploy completes before the call returns, that a name with no agent is refused, that unresolved skills/connectors abort the deploy and return a pending list, and that release-policy orgs return an evaluation instead of a version. It also states the auth requirement ('Requires connecting a Valet account').

Agents need to know what a tool does to the 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 and the routing rule in the first sentence, then organized into clear paragraphs (modes, tree requirements, mutation semantics). It is long, and a few clauses (e.g., the idempotency-key restatement, the merge-on-moved-main detail) could be trimmed, but nearly every sentence earns its place.

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

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

For a complex, destructive, no-output-schema tool this covers everything an agent needs: prerequisite creation, both payload modes, required file layout, failure behavior, return shape ('the answer carries the release version'), and the follow-up path (get_service, get_evaluation with wait_seconds 20). No output schema is needed because returns are described.

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

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

Schema coverage is 100%, so the schema already documents each field; the baseline would be 3. The description adds real meaning on top: it explains the files-vs-push mutual exclusivity ('Pass files or push, not both'), the full push workflow (create_push → run recipe → pass push_id and commit sha), and that valet.yaml/SOUL.md must be at the root. That exceeds what the schema alone conveys.

Input schemas describe structure but not intent. Descriptions should explain 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 source as an agent') and immediately scopes it against siblings: 'when the work is an agent that answers on a channel or runs on a schedule, not a website or an app.' An agent can distinguish this from publish_app, publish_site, and publish_skill 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 ('agent that answers on a channel or runs on a schedule'), when-not (website or app), a required prerequisite ('Apply the governance skill before calling', 'create it first with create_service'), and a decision rule between the two modes ('Use push when you can run git with network access...'). Nothing about routing 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?

The description adds substantial behavior beyond the annotations: publishing replaces the app's source, regenerates valet.yaml, returns a build id, and requires polling get_build until deploy_state is up, crashed, or refused. It also explains crash behavior, release delay, privacy defaults, and access control, and it is consistent with the destructive and non-read-only annotations.

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

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

The description is front-loaded with purpose and is generally dense with useful operational detail rather than filler. However, it is very long for a tool description and could be easier to scan with clearer sectioning, even though most sentences carry real behavior or workflow guidance.

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

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

Given the tool's complexity, eight parameters, nested objects, and no output schema, the description is complete enough to guide correct invocation. It covers prerequisites, source submission modes, build polling, crash handling, environment/resource follow-up, privacy, and authentication requirements.

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

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

Even though schema coverage is 100%, the description adds important meaning: files and push are alternatives, push requires the create_push id and commit sha, title and description are required with files, discard_draft is not used with push, and idempotency_key changes repeat-call behavior. It also clarifies content constraints such as text-only files and dependency manifests.

Input schemas describe structure but not intent. Descriptions should explain 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 gives a specific verb and resource: publishing source as an app that Valet builds and runs behind its own URL. It also explains the app use case as needing a server, background process, or database. It does not explicitly contrast itself with sibling publish tools such as publish_site, publish_agent, or publish_skill, so sibling differentiation relies on the word 'app' and the use-case condition.

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

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

The description explicitly says when to use this tool, requires creating the app first with create_service, and gives concrete conditions for choosing files versus push. It also states that files and push are mutually exclusive and supplies the follow-up workflow for polling builds and attaching resources.

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 declare readOnly=false/destructive=true/openWorld=true, but the description adds real behavioral context the agent could not infer: the site must already exist (create_service first) and a name holding no site is refused; anonymous sites are public to anyone with the link and may be removed 36 hours after creation unless claimed; the response carries a claim URL and a reusable site_token; and a policy-governed account publish may return 'evaluation' requiring get_evaluation(wait_seconds 20). It is consistent with destructiveHint=true ('Publishing to it replaces its files') and idempotentHint=false (idempotency is opt-in via idempotency_key, not a default), so no contradiction.

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

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

It is front-loaded correctly (purpose first, then governance, then requirements, then delivery, then account/token, then policies), but it runs to roughly 350+ words and includes style guidance aimed at the writer ('Write them for the person who will come back to this page in a month') that belongs in a skill. Several sentences duplicate the 100%-covered schema rather than adding new information.

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

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

For a 9-parameter, nested, mutation tool with no output schema, the description supplies everything needed to call it correctly: preconditions, mutual exclusion of the two content paths, failure modes, the shape of the result (claim URL, site_token), and the release-policy follow-up. Without an output schema this coverage is doing the work the schema cannot.

Complex tools with many parameters or behaviors need more documentation. 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 genuinely adds semantics beyond the schema: files and push are mutually exclusive ('Pass files or push, not both'), title and description are mandatory with files and a call missing either is refused, and site_token should be reused to revise rather than create a duplicate site. It stops short of 5 because most of this restates the already-rich 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?

The description opens with a precise verb+resource: 'Publish files as a live website, served over HTTPS at its own URL,' and adds scope ('static artifact,' 'files carries the text of the pages'). It clearly differentiates from create_push and create_service, but the three 'publish_*' siblings (publish_app, publish_agent, publish_skill) are never named or contrasted, so an agent has no explicit cue here for why this is the site tool rather than the app tool.

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

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

Explicit when-to-use triggers are given ('when a report, essay, slide-like narrative, dashboard ... reads better at a live URL'), plus a decision rule between the two delivery modes ('Use push when you can run git with network access, when the site is large or holds binary files, or when you changed a clone of its source'), plus the precondition for anonymous ('only when the user explicitly wants a temporary public site') and the create_service prerequisite.

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 goes well beyond them: it spells out that the previous version's content is replaced for every reader, that files silently drops omitted files including binaries, that identical content dedupes with no new version, that idempotency_key makes retries safe, that a stale base_version publishes nothing, and that a Valet account must be connected.

Agents need to know what a tool does to the 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: the core action and the edits/files/push choice land first, with conflict handling and well-known-name caveats after. A few sentences (e.g., the well-known-name governance tangent) run long, but each carries a distinct behavioral rule, so nearly every sentence earns its place.

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

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

For a 7-parameter, nested-object, no-output-schema mutation tool, the description covers the full decision surface: source selection, versioning and conflict recovery, dedup and retry semantics, auth, and the special well-known-name case. 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 real meaning: it states the mutual exclusivity of edits/files/push ('Pass exactly one of'), the default resolution of skill from SKILL.md frontmatter with files, and that base_version is required with edits but optional otherwise. These conditional requirements go beyond the per-field 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 and resource ('Publish the next version of an organization skill that exists') and immediately scopes it against siblings: create_service for new skills, create_push for the push source, get_skill for the base version. An agent can distinguish this from publish_agent, publish_app, and publish_site 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?

Explicit when-to-use guidance throughout: exactly one of edits/files/push, prefer edits for partial changes, files for whole-tree replacement, push when git with network access is available. It also tells the agent when to reach for a well-known name (governance, security, design-system) and to show content first, and names the alternative paths (create_service, get_skill, list_skills).

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?

With annotations declaring destructiveHint=true and idempotentHint=false, the bar is lower, yet the description goes far beyond them: the old address stops serving, the old name becomes available to another service, agent channels survive because they address by id, the architect agent cannot be renamed, well-known skill names are preserved, and a new SKILL.md version is published with holding agents picking up the change. This is unusually rich behavioral disclosure for a mutation.

Agents need to know what a tool does to the 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 in the first sentence, followed by kind-specific behavior in a logical sequence. It is long but nearly every clause carries distinct, non-redundant information; only the density slightly hurts scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 complex rename affecting four entity kinds, the description covers the per-kind consequences, the permission/account requirement, the immutable special case (architect agent), and even the answer shape for skills. With no output schema, the description steps in where needed and leaves nothing critical to inference.

Complex tools with many parameters or behaviors need more documentation. 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 nonetheless adds real meaning: it clarifies how kind is used to force a refusal on a mismatched name, and that new_name becomes the first host label of the new URL for site/app/skill. org_name default behavior is left entirely to the schema, which keeps this from being 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?

States a specific verb+resource ('Rename a website, app, agent, or skill') and enumerates the entity kinds it operates on, which lets an agent distinguish it from siblings like create_service, destroy_service, or restart_service. The title and opening sentence align precisely with the operation.

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

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

Explains the routing condition for the optional kind parameter ('Pass kind to say which you mean; a name holding another kind is then refused rather than renamed') and notes the account prerequisite. It gives clear usage context but never names an alternative tool or an explicit when-not-to-use case beyond the kind refusal.

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?

Annotations already declare destructive=true and idempotent=true, and the description adds concrete consequences beyond them: scaling down stops running processes, scaling web to 0 takes the URL offline, changing size restarts processes, and setting an existing value changes nothing. The instruction to confirm with the user before scaling down is exactly the operational guidance an agent needs for 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?

Dense but front-loaded: the core action comes first, then per-kind rules, then consequences and caveats. Some redundancy with the schema ("Give count, size, or both; omitting one keeps it" appears in both places) slightly inflates length.

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

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

No output schema exists, and the description covers everything needed to invoke correctly: required fields per kind, defaults for omitted params, size semantics, refusal cases, account prerequisite, and destructive side effects.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining that process_type is a Procfile type such as web, that count is bounded by the organization's cap, and that size values differ in stop behavior and trigger a restart. Minor overlap with schema text keeps it below 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?

Opens with a precise verb+resource: setting process count and/or machine size for one process type of an app or agent. It clearly separates the two target kinds (app vs agent) and is distinguishable from siblings like restart_service, rename_service, and create_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?

Gives explicit per-kind rules (app needs process_type + count; agent count is 0 or 1), states that omitting count/size keeps the current value, and names exclusions: websites are refused and changing an agent's model is not offered here. It also flags the prerequisite of connecting a Valet account.

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

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

Goes well beyond the annotations: it discloses that Valet calls the endpoint's describe operation before saving and saves nothing on failure, that release files leave Valet's control once fetched (substantiating destructiveHint/openWorldHint), that later-requested files render the endpoint unavailable until re-saved, and that non-secret {{NAME}} references are refused. This is exactly the kind of side-effect and irreversibility detail an agent needs before invoking.

Agents need to know what a tool does to the 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 is front-loaded in the first sentence, and the four paragraphs map cleanly to purpose, data-sharing consent, credential handling, and account requirements. It is dense but long, and the {{NAME}} example plus the 'list_policies shows checkers' aside are repeated/tangential enough to keep it off a 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?

Despite having no output schema, the description explains the return value ('The answer names the files the endpoint asked for'), covers auth/prerequisite setup, header credential format, replacement semantics, and the failure/atomicity behavior. Nothing meaningful 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 coverage is 100%, so the schema already documents url, checker, headers, and org_name; baseline would be 3. The description adds genuine value beyond it by explaining {{NAME}} resolution timing, the prohibition on literal credential values, the refusal rule for non-secret variables, and the org_name default behavior.

Input schemas describe structure but not intent. Descriptions should explain 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 names a specific verb pair (add or replace) and resource (organization checker), then defines what a checker actually is — an org-owned HTTPS endpoint implementing Valet's Checker API. It implicitly separates itself from destroy_checker (removal) and list_policies (viewing), so 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?

It gives strong contextual guidance: prerequisites ('Requires connecting a Valet account'), an explicit user-confirmation step, and a preparatory step (have the user set the secret env var first). It references set_policy and list_policies as related tools, but never states an explicit 'do not use this when…' exclusion, 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?

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?