BEON PASS

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description adds one behavioral constraint beyond that — the invitation must be addressed to the signed-in account — but says nothing about irreversibility, error cases (expired/revoked invitations), or whether an existing membership is overwritten. With annotations carrying the main load, a 3 is appropriate.

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

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

One sentence, front-loaded with the action, no filler or redundancy. It is efficient, though its brevity is partly a symptom of the missing detail scored elsewhere rather than deliberate tightness.

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

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

For a destructive, non-idempotent mutation with no output schema and a completely undocumented parameter, the description is thin. It omits what success produces (membership granted), what failures look like (expired/revoked/already-used invitation), and any auth prerequisite detail beyond the signed-in-account hint.

Complex tools with many parameters or behaviors need more documentation. 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 0% for the single parameter, so the description must compensate and largely does not. It never explains where invitation_id comes from, that it is a UUID, or that it must reference an invitation belonging to the caller; only the indirect 'addressed to the signed-in account' phrase hints at scoping.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Accept') and resource ('organization invitation') with a scoping qualifier ('addressed to the signed-in account'). An agent can immediately tell this is the invitation-acceptance action, distinct from the checkpoint/app/railway/supabase/vercel siblings, though it does not name a sibling to differentiate against because none is close.

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

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

No when-to-use guidance, no prerequisites, no alternatives named. The phrase 'addressed to the signed-in account' hints at a precondition but is not framed as guidance (e.g., what to do if the invitation was sent to another address, or how to list pending invitations first).

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 destructiveHint=true and openWorldHint=true, the description usefully adds that there are 'No provider writes', that exact account/project/branch-head/routing and health checks must pass first, and that either native confirmation or an exact legacy one-use approval is required. These are behavioral details beyond what the annotations provide, though the reversibility of the recorded adoption is not described.

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

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

Four short, dense sentences that are front-loaded with the core action and then the preconditions. Every sentence carries substantive information, though the phrasing 'exact legacy one-use approval' and 'exact ... checks' is terse enough to be slightly opaque.

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

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

For a destructive, non-idempotent adoption operation with no output schema, the description covers preconditions and confirmation modes reasonably well. But with 0% parameter coverage and no output description, it leaves the agent uncertain about several required inputs and about what the recorded result contains.

Complex tools with many parameters or behaviors need more documentation. 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 0%, so the description must carry the burden for six parameters. It obliquely gestures at account/project/branch-head (app_id, commit_sha) and the 'one-use approval' (approval_id), but says nothing about expected_revision, deployment_id, or protected_deployment, which are required or meaningful 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?

The description states a specific verb and resource: 'Record an existing current production deployment.' It also names the preconditions (account/project/Git branch-head/routing and health checks), so the agent understands the scope of the operation. It does not explicitly distinguish itself from close siblings like beon_verify_app_release or beon_reconcile_app_release.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implies the tool is used to establish a production baseline ('before using it as a production baseline') and mentions confirmation pathways, giving some context. However, it never states when to prefer this over sibling tools such as reconcile or verify, nor when not to use it.

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

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

Annotations already declare destructiveness, open-world access, and non-idempotency, so the bar is lower. The description does add real behavioral context beyond them — that a provider metadata inspection must be authorized, that request_id must be stable, that the description field must avoid secrets, and that no provider write/backup occurs. It still omits the effect of a revision mismatch and what a checkpoint actually captures.

Agents need to know what a tool does to the 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 only three sentences and front-loads the save action, but the opening clause ('after authorized provider metadata inspection') is jargon-heavy and vague, and the parameter guidance is wedged into the middle rather than structured as an ordered list.

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

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

For a destructive, non-idempotent mutation with 10 parameters, no output schema, and 0% schema coverage, the description is too thin. It does not explain conflict behavior, what the checkpoint stores, or how the many fields relate, leaving an agent likely to misuse it.

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

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

Schema description coverage is 0% across 10 parameters, so the description carries the full burden, yet it only touches expected_revision, expected_head_id ('branch head, null initially'), and request_id. Required fields such as app_id, environment, commit_sha, and description's semantics, plus optional branch/task_refs/release_id, are left entirely to the bare 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+resource ('Save a named checkpoint of an exact source commit'), which is clearly distinguishable from siblings like beon_pin_app_checkpoint or beon_prepare_app_checkpoint_restore. However, it never explicitly contrasts itself against those nearby tools, so an agent must infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implies a precondition ('after authorized provider metadata inspection') and a boundary ('No backup purchased or provider write'), which hints at when it applies. But there is no explicit when-to-use/when-not guidance relative to the many checkpoint/prepare siblings, leaving usage largely inferred.

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, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so safety-profile burden is largely covered. The description does add real context beyond that — newer versions are preserved and no code/deployment is affected — but it says nothing about reversibility, auth needs, or the meaning of expected_revision concurrency.

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

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

Three tight sentences with the core action front-loaded and the Git-branch disclaimer placed early where it prevents the most likely misread. No filler, though the closing usage sentence is terse enough to be slightly cryptic.

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

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

For a destructive, non-idempotent mutation with no output schema and five undocumented required params, the description leaves meaningful gaps. It gestures at the return ('returned branch') which partially offsets the missing output schema, but the concurrency and environment semantics an agent needs to call it correctly are absent.

Complex tools with many parameters or behaviors need more documentation. 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 0% across five required parameters, so the description must compensate but barely does. 'From a prior version' loosely maps to checkpoint_id and 'returned branch' hints at output, but name, environment (staging/production), and especially expected_revision (optimistic-concurrency token) get no explanation.

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

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

States a specific verb+resource ('Create an alternative checkpoint history from a prior version') and explicitly rules out confusion with Git branching ('Does not create a Git branch'), which helps distinguish it from cousins like supabase_create_branch. However, it never differentiates itself from the closest sibling, beon_create_app_checkpoint, so an agent still has to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 line 'Use the returned branch explicitly in captures' gives a downstream usage hint, implying this tool is a setup step before capture operations. But there is no when-to-use/when-not guidance relative to beon_create_app_checkpoint or beon_pin_app_checkpoint, so selection among siblings remains 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 declare destructive/non-idempotent/openWorld, so safety is covered structurally. The description adds genuinely non-obvious behavior on top: wildcard tool entries extend to future tools, host confirmation settings are not overridden, and secret entry is handled elsewhere. That is real added context, though it says nothing about revocability or blast radius of a destructive grant.

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

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

Four short, front-loaded sentences with no filler; the core action leads and caveats follow. Slightly clipped to the point of being telegraphic, but efficient.

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

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

For a destructive, non-idempotent mutation with 7 undocumented parameters and no output schema, the description omits far too much: what a grant authorizes, duration semantics, what allow_high_impact changes, and how to revoke. The added caveats are helpful but insufficient.

Complex tools with many parameters or behaviors need more documentation. 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 0% on 7 parameters, so the description carries the full burden and mostly fails. Only an indirect hint at the tools array (wildcards) is present; duration options, provider enum, approval_id vs connection_id, and especially allow_high_impact are never explained.

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

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

States a specific verb+resource: 'Create a BEON PASS standing authorization.' An agent can tell this creates a grant object, though 'standing authorization' is domain jargon and the description does not distinguish it from the sibling beon_update_autopilot_grant.

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

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

Two boundary statements ('Does not override the host's own confirmation settings', 'Private secret entry is always separate') clarify scope limits, but there is no when-to-use guidance, no mention of the update sibling, and no prerequisites for the approval_id/connection_id inputs.

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 the safety profile (readOnly=false, destructive=false, non-idempotent, open-world), so the bar is lower. The description adds two non-obvious facts not in those annotations: ownership is bound to the signed-in person and the creating AI client does not receive administration rights over the new org — a meaningful scope limit an agent would otherwise assume away.

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

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

Two short sentences with zero filler. The action and its scope are stated first, and the access caveat follows immediately after.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 create tool with no output schema, the description covers the key permission trap but omits anything about slug semantics, what identifies the returned organization, or how a caller would subsequently act on it. Adequate but with clear gaps.

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

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

Schema description coverage is 0%, so the description is the only place parameter meaning could live — and it says nothing about 'name' or 'slug'. The slug's format pattern, uniqueness expectation, and human-readable-vs-identifier distinction are left entirely unexplained.

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

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

Specific verb+resource: 'Create a BEON PASS organization', with the ownership scope spelled out ('owned by the signed-in person'). No sibling tool creates a BEON PASS organization, so the resource alone disambiguates it from supabase_create_project, railway_create_project, and vercel_create_project.

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

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

The description says what the tool does but never says when to reach for it, what must pre-exist (a signed-in person, a free slug), or how it relates to the many other create_* siblings. The only conditional content is a permission caveat, which is behavioral rather than usage 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=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious domain semantics beyond that: pinning is not a retention extension and not a recovery authorization. It still omits conflict/expected_revision behavior, 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?

Two short sentences, front-loaded with the action and followed by the key constraint; no filler, no redundancy. 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?

With 5 required params, 0% schema coverage, no output schema, and a destructive non-idempotent mutation, the description is too thin. An agent gets no guidance on the required revision/concurrency parameter, error conditions, or what the call returns.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 5 required parameters, so the description must compensate — and it largely does not. 'Pin or unpin' only weakly implies the `pinned` boolean; app_id, environment, checkpoint_id, and especially expected_revision (optimistic concurrency) go entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 pair and resource: 'Pin or unpin a version in app history.' This clearly distinguishes it from creation/restore siblings like beon_create_app_checkpoint or beon_prepare_app_checkpoint_restore, though it never names those siblings 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?

The second sentence provides negative scoping (does not extend backup retention, does not grant recovery permission), which steers the agent away from treating this as a protection/recovery tool. However, there is no positive when-to-use guidance or explicit alternative named, leaving usage largely implied.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, non-idempotent and open-world, so the safety profile is covered. The description adds real value beyond that by clarifying the tool only prepares a proposal ('Returns an existing release proposal, not execution authority') and confines itself to preview code with 'no Live change or data restore'.

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

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

Three tightly packed sentences with the core action front-loaded and zero filler. The density is effective, though the jargon ('closed stateless fixture', 'independently pinned static-export recipe') borders on cryptic.

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

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

For a destructive, non-idempotent mutation the description does cover scope, return semantics, and safety framing, and no output schema exists so return detail is minimal. However, with 0% schema coverage the unexplained expected_revision concurrency parameter leaves a gap 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 description coverage is 0% across four required params. The description hints at checkpoint_id ('exact checkpoint') and environment ('Preview'), but never explains expected_revision (apparently an optimistic-concurrency token) or app_id, and adds no format or constraint guidance. This materially under-compensates for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain 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 ('prepare ... restoration') and a precise resource/scope ('code-only restoration to isolated Preview from an exact checkpoint'). The narrowing clauses ('no Live change or data restore') help distinguish it from writing siblings like beon_create_app_checkpoint or beon_pin_app_checkpoint, though no sibling is named outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 genuine applicability constraints ('Closed stateless fixture or independently pinned static-export recipe only') and an exclusion ('no Live change or data restore'), which tells an agent both when this applies and when it does not. It stops short of routing to alternatives (undo/redo/release), so it falls below 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 declare destructive=true, idempotent=false, and openWorld=true, so safety is partly covered. The description adds real behavioral context beyond them: ambiguity is never auto-resolved ("Ambiguous branches are never guessed") and redo does not discard newer history ("no newer history is erased"), which materially shapes agent expectations. It omits whether a follow-up commit/confirmation step 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?

Three short, front-loaded sentences with no filler; the operation and its scope restriction are stated first. The dense, undefined jargon ("Prepare Redo", "pinned static-export recipe") costs some readability without adding length.

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

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

For a destructive, non-idempotent mutation with five required parameters at 0% schema coverage and no output schema, the description is under-specified. It never explains the prepare/commit lifecycle (what a successful "prepare" produces or whether a second call is needed) nor the role of expected_revision, which an agent must understand 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 0% across five required parameters, so the description carries the full burden and fails to explain any of them. app_id, environment, checkpoint_id, expected_revision (an optimistic-concurrency guard), and current_checkpoint_id are never mentioned or defined, even though the concurrency parameters are exactly where an agent would err.

Input schemas describe structure but not intent. Descriptions should explain 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 operation ("Prepare Redo") and the target resource ("an explicitly selected direct child version in Preview"), so the agent can distinguish it from a generic restore. It does not explicitly contrast with the obvious sibling beon_prepare_app_undo, leaving the redo-vs-undo distinction to inference.

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

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

It states an applicability restriction ("Closed stateless fixture or independently pinned static-export recipe only") which is a genuine when-to-use condition. However, it names no alternative tool and gives no explicit when-not-to-use guidance relative to beon_prepare_app_undo or beon_prepare_app_checkpoint_restore.

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, openWorldHint=true, idempotentHint=false. The description adds valuable negative disclosures not in the annotations - it does not publish, does not copy credentials, does not prove runtime data safety - which tells the agent the blast radius is bounded to a recorded proposal, and it states the production baseline precondition.

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

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

Three sentences, front-loaded with the core action, then preconditions, then explicit non-goals. Dense but every sentence earns its place; minor jargon cost does not justify penalizing structure.

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

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

For a destructive, non-idempotent, open-world mutation with no output schema and 7 undocumented parameters, the safety non-goals are a good start, but the description never explains the parameters, the expected response, or how 'record a proposal' relates to the later verify/reconcile/publish steps in the release lifecycle.

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

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

Seven parameters with 0% schema description coverage, and the description names none of them. 'exact-commit', 'build/config/migration boundary', and 'same-environment baseline' only obliquely gesture at commit_sha, config_requirements, migration_ids, and environment; app_id, expected_revision, and previous_release_id are entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 compound action: 'inspect exact-commit source boundaries and record a code-only Git/Vercel proposal.' This distinguishes it from publishing/deploying siblings, though the jargon ('source boundaries', 'code-only proposal') makes the exact output object ambiguous for an agent unfamiliar with BEON's model.

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

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

Gives real conditions: production requires an unchanged build/config/migration boundary against a verified same-environment baseline, and first releases need separate review. It does not name direct sibling alternatives (e.g. reconcile/verify), but the production-vs-first-release gating is concrete usage 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 flag destructiveHint=true and idempotentHint=false, but the description adds the non-obvious behavioral trait that newer history is preserved, and that this is a 'Prepare' (staging) step rather than the authorized publish. That materially refines the destructive semantics the annotations alone would imply.

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

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

Two sentences, front-loaded with the action and its scope before the restriction and the publishing caveat. The jargon is dense but every clause carries information; little is wasted.

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

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

For a destructive mutation with four required parameters and no output schema, the description covers the what and the when but leaves all parameter meaning unexplained and does not clarify the staged/preview result. Annotations carry the safety profile, which keeps this at a minimum-viable 3 rather than lower.

Complex tools with many parameters or behaviors need more documentation. 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 0% across four required parameters (app_id, environment, checkpoint_id, expected_revision). The description names none of them and explains no semantics such as what expected_revision guards against or what checkpoint_id refers to, so it does not compensate for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Prepare Undo'), a resource (parent checkpoint), and a scope ('in Preview'), with the key qualifier 'preserving all newer history'. It implicitly contrasts with the redo sibling via the word 'Undo', but never names an alternative, so it stops short of a clean 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 gives a usage restriction ('Closed stateless fixture or independently pinned static-export recipe only') and a routing hint ('publishing still uses the existing separately authorized deployment operation'). However the restriction is opaque jargon and no sibling (e.g. beon_prepare_app_checkpoint_restore, beon_prepare_app_redo) is named, so an agent must infer which case applies.

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

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

Beyond the annotations it adds real behavioral context: the call does not go live immediately but issues a secure human review request (which mitigates the flagged destructiveHint), the request_id enables safe retry, and credentials are entered out-of-band rather than in the call. It still does not say what state changes upon approval, keeping it below 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?

Three tight clauses with the action and its outcome front-loaded and no filler. The telegraphic fragments leave some ambiguity (e.g. 'credentials entered privately'), but the sizing is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-required-parameter, nested-array, destructive publishing tool with no output schema, the description is thin: it never explains revision semantics, the fingerprint requirement, or how the review request resolves. An agent can identify the tool but not invoke it confidently.

Complex tools with many parameters or behaviors need more documentation. 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 only 40% (request_id and organization_id carry descriptions), so the description must compensate for revision, connection_id and the nested tools[].id/fingerprint. The lone hint about request_id merely restates the schema's own description; nothing explains what revision or fingerprint must be.

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

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

States a specific verb+resource ('Publish exact tested definitions') and the audience scope ('for selected AI access'), clearly separable from beon_test_custom_tool and beon_register_custom_tool. It does not explicitly name which sibling to use instead, so it stops short of 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?

'exact tested definitions' implies this is the step after testing, and 'Returns a secure human review request' implies it is a submission-for-approval action, but no condition or alternative is stated. Usage is only inferable, not spelled out.

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=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them: it explicitly disclaims a deployment retry or provider write, and it discloses the failure mode that 'incomplete, absent, duplicate or still-building evidence keeps the app locked'. It does not say what 'reconcile' mutates locally or whether the operation can be reversed.

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

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

Three short sentences, front-loaded with the operation and its scope, followed by the write-scope exclusion and the failure condition. No filler; every clause carries 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 non-idempotent, destructive mutation with no output schema, the description covers intent, write scope, and lock outcome but omits what the tool actually changes, what it returns, and whether the caller needs elevated permissions. Adequate minimum but with clear gaps.

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

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

Schema description coverage is 0% and the description never mentions app_id or release_id, so neither parameter gains any meaning from the prose. With two required, entirely undocumented parameters, the description fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Reconcile') against a specific resource ('an uncertain original deployment') and qualifies the inputs used ('fresh exact provider source and signed attempt evidence'). It is distinguishable from siblings like beon_verify_app_release or beon_prepare_app_release, though the term 'reconcile' remains domain jargon without a plain-language gloss.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 'No deployment retry or provider write' clause implicitly tells the agent when this tool is NOT the right call and steers it away from retry/write siblings. However, it never states the positive trigger condition (e.g., 'use after an interrupted deploy when the lock state is uncertain') nor names a specific alternative 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?

The description adds real context beyond the annotations: registration triggers a human review request rather than immediate activation, and credentials are never passed through this call. That softens the annotated destructiveHint=true. However, it never explains the review outcome, timing, or what happens if review is rejected, and the 'idempotent request_id' phrasing sits in tension with idempotentHint=false.

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

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

Three short, front-loaded sentences with no filler; the core action leads. The telegraphic style ('Idempotent request_id') is efficient but slightly clipped for an agent parsing semantics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, 6-parameter registration tool with no output schema and 33% coverage, the description covers the review-flow outcome but omits the response shape, approval path, and the meaning of half the parameters. Adequate to start but not complete enough to predict 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 only 33%, so the description should compensate more. It does constrain url (deployed HTTPS) and clarifies the auth flow ('credentials entered privately') and request_id reuse, but it says nothing about organization_id (personal vs org wallet), label, or the protocol enum, which remain locked in the schema.

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

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

A specific verb+resource: registers a deployed HTTPS MCP server. It is clearly distinct from mutation siblings like beon_update_custom_tool or beon_remove_custom_tool, but it never positions itself against beon_test_custom_tool or beon_publish_custom_tools, which are the nearest neighbours in the workflow.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. An agent must infer from 'Returns a secure human review request' that registration is a pre-publication step, but nothing states prerequisites, ordering, or what to do if the server is already registered.

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 adds real context beyond them: the operation does not delete hosting, it returns a human review request (i.e., not immediate execution), and credentials are entered privately. It does not explain the review/approval lifecycle or required permissions, but it meaningfully enriches the safety picture.

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

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

Three front-loaded clauses with the core action first, then the scope boundary, then the return/security behavior. Every clause carries distinct information and there is no filler.

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

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

For a destructive, open-world mutation with no output schema, the description covers the action, its scope limit, the human-review return path, and credential handling. It is largely complete, though it omits permission requirements and the exact meaning/format of revision and connection_id.

Complex tools with many parameters or behaviors need more documentation. 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 50%: request_id and organization_id are documented in the schema, while connection_id and revision are not. The description's only parameter reference ('Idempotent request_id') merely restates what the schema already says, so it does not compensate for the undocumented parameters.

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

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

The description states a specific verb+resource ('Remove BYOT registration and access') and immediately bounds the scope with 'does not delete hosting'. This clearly positions it against register/update custom-tool siblings, though it never names them explicitly, so it stops short of full sibling differentiation.

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

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

Usage is only implied: the verb tells the agent it is used to tear down a BYOT registration, and 'does not delete hosting' implies when it is NOT appropriate. There is no explicit when-to-use, prerequisite, or named alternative against beon_register_custom_tool / beon_update_custom_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?

Annotations already declare the safety profile (destructiveHint=true, idempotentHint=false, readOnlyHint=false, openWorldHint=true). The description adds meaningful context beyond that: it specifies optimistic concurrency, says wallet membership and permissions are reused, and explicitly notes that provider access is never granted. It stops short of describing what gets destroyed or what the return behavior looks like.

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

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

The description is two tight sentences, front-loaded with the core operation and followed by the most important behavioral constraints. There is no filler or repetition.

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

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

For a destructive create/update tool with four parameters, zero schema descriptions, and no output schema, the definition is too thin. It lacks parameter explanations and usage conditions, leaving an agent with significant uncertainty about how 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 0%, and the description does not explain any of the four parameters directly. 'Optimistic concurrency' faintly gestures at expected_revision, but app_id, context, and organization_id remain semantically undocumented.

Input schemas describe structure but not intent. Descriptions should explain 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 clear verb+resource: 'create or update persistent app metadata.' It also adds a differentiating technical constraint, 'optimistic concurrency,' but does not explicitly distinguish this tool from nearby siblings such as checkpoint or release preparation tools.

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

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

There is no when-to-use guidance, no alternatives named, and no conditions under which this tool should be selected over sibling app-management tools. The description mentions permission behavior but not invocation context.

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, readOnlyHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is largely covered. The description adds genuinely new context (a human review request is produced; credentials are entered privately), but the phrase 'Idempotent request_id' sits oddly against idempotentHint=false and is not reconciled, and no retry/review-turnaround behavior is described.

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

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

Three short sentences with no filler, and the most important fact (it returns a review request, not a result) is front-loaded alongside the core action. It errs toward under-specification rather than verbosity.

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

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

This is an 8-required-parameter, no-output-schema tool in a human-review workflow, and the description says nothing about the review lifecycle, what happens after submission, how to poll for the decision, or what fingerprint/revision must match. For a destructive, open-world operation with low schema coverage, this is materially incomplete.

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

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

Only 2 of 8 parameters (25% coverage) carry schema descriptions, so the description is expected to compensate and largely does not. 'Approved input and expected output' loosely maps to the input and expected_structured_output params, but tool_id, revision, fingerprint, and connection_id are unexplained in both the schema and 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 states a concrete action (test an exact tool with approved input and expected output) and then clarifies the actual output shape: a secure human review request rather than an immediate execution result. That second sentence is what makes the purpose distinguishable from the sibling register/update/publish custom-tool tools, though the phrase 'exact tool' is idiosyncratic and the sibling relationship is never named.

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

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

There is no statement of when to call this versus beon_register_custom_tool, beon_update_custom_tool, or beon_publish_custom_tools, and no prerequisites (e.g., tool must already be registered) are given. The agent must infer usage entirely from the name.

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=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it clarifies the whole policy is replaced rather than patched, and that host confirmation settings are out of scope for this call.

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

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

Two tight sentences with the replacement semantics front-loaded and the scoping caveat second. Nothing is wasted, though the caveat sentence is a minor tangent relative to the unexplained parameters.

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

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

For a destructive, non-idempotent mutation with eight parameters and no output schema, the description is too thin. It should at minimum characterize the required policy inputs (tools, resources, provider) and the role of approval_id/connection_id, none of which is addressed.

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

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

Eight parameters at 0% schema description coverage, and the description never mentions any of them. It gestures at 'policy' without explaining that tools/resources/provider define it, and says nothing about duration, approval_id, connection_id, or allow_high_impact, leaving an agent to guess from names 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 and resource: 'Replace this AI client's standing authorization' plus the replacement scope ('with the exact supplied policy'). This reads clearly as the update counterpart to beon_create_autopilot_grant, though it never names that sibling to sharpen the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 word 'Replace' implies full-overwrite semantics rather than a merge, which is useful context, but there is no explicit when-to-use statement or routing to the alternatives (beon_create_autopilot_grant, beon_accept_invitation). Usage is inferable, not 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 establish destructiveHint=true and openWorldHint=true, so safety is partly covered. The description adds genuinely useful context beyond them: it returns a human review request and credentials are entered privately, clarifying this is a gated/approval flow. It still omits what state is destroyed by a "changed definition" and what permissions are 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?

It is short and telegraphic, with no wasted words, but the terseness crosses into under-specification rather than economical clarity. The fragments are not ordered into a useful purpose-then-usage progression an agent can act on.

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

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

This is a destructive, open-world mutation with no output schema, four required params, and no annotation narrative; the description should carry more weight. It says a review request is returned but omits prerequisites, permission requirements, and what specifically changes, leaving an agent unable to call it confidently.

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

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

With only 50% schema description coverage, revision and connection_id are undocumented in both schema and description. The one param note ("Idempotent request_id") merely restates the schema's own request_id description rather than adding meaning, and "credentials entered privately" does not map to any declared parameter.

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

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

"Rediscover a deployed update" is opaque and metaphorical; it never states that the resource is a custom tool definition or what aspect of it is being updated. The name/annotations carry more meaning than the description does, and an agent cannot distinguish this from beon_register_custom_tool or beon_publish_custom_tools on the text alone.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling alternative is named. The phrase "changed definitions lose access" gestures at a condition but is too cryptic to route the agent, leaving usage entirely 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?

With annotations already declaring openWorld and destructive hints, the description adds meaningfully: the bypass secret arrives through a one-use encrypted private input rather than a tool argument, evidence storage is limited, and it explicitly disclaims proving all app behavior or database recovery. It does not explain what makes the operation destructive, but the secret-handling and scope-limit disclosures are substantive context beyond the annotations.

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

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

Three sentences, front-loaded with the core action and with no filler. The middle sentence is dense and the phrasing is slightly awkward, but every sentence contributes a distinct fact (scope, secret channel, limitations).

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

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

For a security-sensitive, non-idempotent operation with no output schema and 0% parameter coverage, the description covers the distinctive secret mechanism and states its own limitations, which is the most valuable content. It still omits what evidence is returned, the role of approval_id, and why the call is flagged destructive.

Complex tools with many parameters or behaviors need more documentation. 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 0% across five parameters, so the description must carry the load. It explains protected_preview and protected_deployment and how the bypass secret is supplied, but says nothing about app_id, release_id, or approval_id — the required pair and the approval gate are left entirely to the raw 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?

"Verify the exact deployment, project and health commit" gives a verb plus resources, but the object of verification is grammatically muddled and it never distinguishes itself from the adjacent siblings beon_prepare_app_release and beon_reconcile_app_release. An agent can infer it is a verification step for a release, but not how it differs from the prepare/reconcile pair.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 does explain the conditional use of the optional flags — protected_preview for staging, protected_deployment for an exact lifecycle-enabled deployment — which is genuine when-to-use guidance. However, there is no guidance on when verification is required, when it should be skipped, or which sibling to pick instead.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: an external approval gate via BEON PASS. It does not, however, explain what cancel does semantically (e.g., whether an in-progress build is aborted) or any failure modes.

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

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

Two short, front-loaded sentences with the core verb-resource statement first and the approval prerequisite second; no wasted wording. It is slightly cryptic about the undefined term 'BEON PASS', which keeps it from 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?

For a destructive, non-idempotent mutation with 8 undocumented parameters, no output schema, and only one required field, the description is thin. The approval gate is the one substantive addition; there is no guidance on parameter usage, expected result, or what happens on failure.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 8 parameters with only 1 required, and the description adds no parameter meaning at all. The mention of 'BEON PASS' faintly hints at the purpose of the beon_* fields, but the required 'id', the approval_id, and the enum-constrained beon_environment/beon_connection_id remain entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 clear verb+resource ('Cancel a deployment'). It distinguishes from write operations like railway_create_* and railway_delete_project, but does not differentiate from the closely related siblings railway_stop_deployment, railway_restart_deployment, and railway_rollback_deployment, which an agent will need to tell 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?

It gives a precondition ('Requires exact user approval in BEON PASS') but no when-to-use guidance and no contrast against the obvious alternatives (stop, restart, rollback, delete). An agent cannot infer from this whether 'cancel' is preferred over 'stop' for an in-flight deployment.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuine value beyond that by warning it 'can modify production and deploy services,' which is material impact context. It omits any mention of the approval_id workflow or permissions the schema implies.

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

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

Two tight sentences, no filler, with the action and its risk front-loaded. Every clause 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?

This is a destructive, production-affecting mutation with 10 parameters, an approval mechanism, and no output schema, yet the description explains almost none of the operational surface. Given the complexity and the 0% schema coverage, the description is far too thin to call the tool 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 description coverage is 0% across 10 parameters, so the description carries the full burden and largely fails it. Only 'deploy services' loosely gestures at skipDeploys; environmentId, commitMessage, approval_id, and the beon_* parameters go unexplained in both description and schema.

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

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

States a specific verb and resource: 'Apply the provider's current staged changes,' which an agent can distinguish from read-only siblings. It does not explicitly name railway_inspect_staged_changes as the counter-tool, only hinting at reviewing first, so differentiation is implied rather than stated.

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

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

'review staged changes in Railway first' implies a prerequisite step before committing, which is useful context. However it never names the alternative tool (railway_inspect_staged_changes) or states when-not to use this, leaving the routing 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 readOnlyHint=false, destructiveHint=true, idempotentHint=false, and openWorldHint=true. The description adds meaningful behavioral context beyond those annotations: changes may restart production, and the operation requires exact user approval in BEON PASS. It does not, however, explain approval mechanics, permission requirements, or reversibility.

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

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

Two short sentences with no wasted wording. The purpose is front-loaded, followed immediately by the production-restart risk and approval requirement.

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

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

For a destructive, non-idempotent mutation tool with 10 undocumented parameters and no output schema, the description is minimally adequate but incomplete. It conveys the production risk and approval gate, which are critical, but it omits parameter semantics and any routing guidance relative to read or other configuration tools.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 10 parameters, including a nested input object with five build/deploy fields. The description only gestures at 'build/deploy settings' and does not explain required IDs, approval fields, or the individual nested fields such as numReplicas, buildCommand, or startCommand.

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

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

The description uses a specific verb and resource: 'Update service build/deploy settings for an environment.' This distinguishes it from read-oriented siblings like railway_get_service_configuration and from other mutation tools, but it does not name an alternative or explicitly contrast with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 no explicit when-to-use, when-not-to-use, or alternative routing guidance. An agent must infer that this is the tool for changing existing service configuration by reading the verb 'Update' and the scope 'for an environment.'

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=false, so the risk profile is known. The description adds genuinely useful value with 'Can affect live routing', a concrete impact warning not captured by annotations. However, it omits whether DNS/verification is required, whether the domain must already be owned, and what happens on the live service during propagation.

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

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

Two short sentences, front-loaded with the action and immediately followed by the impact warning. Nothing is wasted, though the extreme brevity is under-specification rather than true tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 12-parameter mutation tool with no output schema and 0% schema description coverage, the description is far too thin. An agent gets no guidance on required versus optional fields, port targeting, or domain verification, all of which materially affect a successful call to a destructive, non-idempotent operation.

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

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

Schema description coverage is 0% across 12 parameters, and the description names no parameters at all. The four required identifiers (projectId, environmentId, serviceId, domain), targetPort, and the non-obvious approval_id/beon_* fields are left entirely unexplained, so the description does nothing to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Attach') and resource ('custom domain') with the scope ('to a service environment'), which is clear and distinguishable from write siblings like railway_create_service_domain. It stops short of explicitly contrasting with that near-identical sibling, so no sibling differentiation credit beyond the resource wording.

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

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

No when-to-use, prerequisites, or alternative guidance is given. With siblings such as railway_create_service_domain and railway_delete_custom_domain in the same namespace, the description never says which one applies or when this should be chosen over them.

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

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

Adds real traits beyond the annotations: optional configuration cloning via a source environment, the fact that initial deployments are skipped, and an approval gate in BEON PASS. Annotations already cover the safety profile (write, non-destructive, non-idempotent, open-world), so this is meaningful added 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?

Three tight sentences with the core purpose front-loaded and no filler. Every sentence contributes a distinct fact (creation, cloning option, skipped deployments, approval requirement).

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

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

For a 10-parameter mutation tool with 0% schema coverage and no output schema, the description is thin. It never explains the beon_* context fields, the approval_id mechanism, or what a cloned configuration actually includes, leaving the agent under-informed for invocation.

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

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

Schema description coverage is 0% across 10 parameters, so the description carries the burden and largely fails. 'Optionally cloning configuration' loosely maps to sourceEnvironmentId and the approval note loosely maps to approval_id, but the beon_* context parameters remain entirely unexplained in both schema and 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?

States a clear verb+resource ('Create an environment') and adds distinguishing scope: optional config cloning and that initial deployments are skipped. The name and description naturally separate it from railway_delete_environment and railway_list_environments, though no sibling is explicitly named.

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

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

No guidance on when to choose this over railway_create_project or other setup steps, and no alternatives named. The only prerequisite mentioned ('Requires exact user approval in BEON PASS') is a gating condition rather than usage-selection 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=false, destructive=false, idempotent=false, openWorld=true, so the safety profile is partly covered. The description adds genuinely new context: the operation 'May incur usage charges' and requires explicit BEON PASS user approval. Those are consequential side effects and an auth gate not derivable from annotations. It stops short of saying what happens on repeat calls (non-idempotent) or what is returned.

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

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

Three short sentences, each earning its place: purpose first, then the cost warning, then the approval gate. No filler and the most decision-relevant facts are front-loaded.

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

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

Covers purpose, cost, and the approval requirement, which is good for a mutation tool whose annotations already carry the safety hints and which has no output schema to explain. However, for a 10-parameter tool with 0% schema coverage it leaves the approval_id and beon_* parameters entirely unexplained, so an agent cannot confidently construct a valid call.

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

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

Schema description coverage is 0% and the description documents no parameters beyond loosely implying a workspace and a name. Eight of ten parameters — approval_id, beon_app_id, beon_context, beon_resume_id, beon_release_id, beon_environment, beon_connection_id, description — are undocumented in both schema and description. With this coverage gap the description should compensate but does not, so it scores below the baseline.

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

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

States a specific verb and resource ('Create a private Railway project') plus the scoping requirement ('in a selected workspace'). An agent can distinguish it from read/delete siblings like railway_get_project or railway_delete_project. It does not explicitly differentiate from the analogous supabase_create_project / vercel_create_project tools, but the name prefix carries that.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 one real precondition — 'Requires exact user approval in BEON PASS' — which tells the agent when the call will succeed. It offers no guidance on when to choose this over alternatives, no exclusions, and no mention of prerequisites like needing a valid workspaceId from railway_list_workspaces.

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 convey non-readOnly, openWorld, non-idempotent, non-destructive. The description adds genuinely new context on top: that creation may kick off a deployment and incur charges, and that a BEON PASS approval is mandatory. It doesn't explain approval expiry or what the service state looks like after the call, so it stops short of 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?

Three short sentences, front-loaded with the action, then the risk, then the gate. Nothing is redundant and no sentence can be dropped without losing signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 10-parameter mutation with no output schema, the description covers purpose, cost exposure, and the approval prerequisite well. It does not cover the BEON PASS workflow that most of the parameters imply, nor the relationship among the required projectId and name, so an agent still cannot confidently fill the schema.

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

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

Schema description coverage is 0% across 10 parameters, so the description carries the full burden. It hints at source.repo/source.image ('from a repository or public container image') and at approval_id ('Requires exact user approval'), but the seven other beon_* parameters (context, resume/release ids, environment enum, connection id) and the projectId/name distinction are entirely undocumented.

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

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

States a specific verb and resource ('Create a Railway service') plus the two source types (repository or public container image), which the sibling names alone don't reveal. It is distinguishable from railway_create_project and railway_create_environment by the 'service' noun, though it never explicitly contrasts them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 discloses two important conditions ('May trigger deployment and charges', 'Requires exact user approval in BEON PASS'), which is real guidance about consequences. However, it gives no when-to-use vs when-not framing relative to siblings such as railway_deploy_service or railway_configure_service, leaving the routing decision 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 destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds nothing about permanence, permission requirements, whether an existing domain is replaced, or the approval_id workflow — meaningful gaps for a destructive create in an open-world environment. It does not contradict 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?

One short, front-loaded sentence with no waste, but its brevity reflects under-specification rather than efficient information density.

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

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

A 10-parameter destructive create tool with no output schema and no parameter documentation cannot be called correctly from this description alone. It should at minimum explain serviceId/environmentId/targetPort and the approval flow.

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

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

Ten parameters with 0% schema description coverage, and the description mentions none of them. Critical inputs like targetPort, approval_id, and the beon_* metadata fields are completely unexplained in both schema and description, leaving the agent unable to supply them correctly.

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

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

States a specific verb and resource (create a Railway-generated public service domain). The word 'generated' implicitly distinguishes it from railway_create_custom_domain, though it never names that sibling 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?

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative railway_create_custom_domain or railway_delete_service_domain. The agent must infer the generated-vs-custom distinction from a single adjective.

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=false, and openWorldHint=true, so the dangerous profile is covered there. The description adds one genuinely useful piece of context not in annotations — "Provider charges apply" — alerting the agent to cost. However it omits whether an existing service is required, whether the mount point must be empty, and whether approval is needed.

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

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

Two short, front-loaded sentences with no filler, and the core action leads. It is efficient, though arguably under-sized for a destructive 11-parameter 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?

For a destructive, non-idempotent mutation with 11 mostly-undocumented parameters and no output schema, the description is far too thin. It gives no lifecycle context (what a volume attaches to, resulting persistence, cleanup via railway_delete_volume) and leaves the agent guessing at most inputs.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 11 parameters (4 required), and the description provides no parameter guidance whatsoever. The word "attach" faintly hints at mountPath, but projectId, environmentId, serviceId, and the beon_* parameters are entirely unexplained in both places.

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

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

"Create and attach persistent storage" gives a clear verb (create), resource (persistent storage/volume), and an extra action (attach). It distinguishes itself reasonably from sibling volume tools like railway_create_volume_backup or railway_rename_volume, though it never names them or clarifies the create-vs-attach combination.

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

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

There is no guidance on when to create a volume versus using an existing one, no mention of prerequisites (an existing project/environment/service), and no reference to alternatives such as railway_list_volumes or railway_update_volume_mount. Usage must be inferred entirely from the name.

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 readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety/mutation profile is already covered. The description adds only 'Storage charges may apply,' a useful cost warning, but omits permissions, side effects on the volume, and backup lifecycle behavior.

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

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

Two short sentences, front-loaded with the core action and followed by a material caveat. No filler, and the cost note 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 9 parameters, 0% schema description coverage, and no output schema, the description is too sparse to help an agent call the tool correctly. It gives purpose and cost but no parameter meaning or success/return context.

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

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

Schema description coverage is 0% across 9 parameters, and the description names none of them. It does not explain volumeInstanceId (the sole required parameter), the optional name, or the beon_* / approval_id fields, so it adds no semantic meaning beyond the schema.

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

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

States a specific verb ('Create') and resource ('persistent volume backup'), distinguishing it from sibling railway_create_volume and railway_restore_volume_backup. 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?

No guidance on when to use this tool versus alternatives such as railway_list_volume_backups, railway_restore_volume_backup, or railway_lock_volume_backup. The only context is the cost caveat, which does not help selection.

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, non-idempotent, and open-world, so the safety profile is covered. The phrase "interrupt its traffic" adds a real consequence beyond the annotations, but the description says nothing about immediacy, irreversibility, DNS record cleanup, or whether the domain can be re-added.

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

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

A single front-loaded sentence with zero filler, though it is arguably over-compressed for a destructive eight-parameter tool. Nothing is wasted, but nothing is expanded where it would help.

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

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

For a destructive mutation with no output schema, 0% schema description coverage, and an approval_id parameter hinting at an approval workflow, the description is far too thin. It never mentions the approval gate, the context parameters, or what happens to traffic on removal.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 8 parameters, and the description offers no parameter guidance at all. The required `id` and the seven optional beon_*/approval_id context parameters are left entirely for the agent to infer from names and patterns.

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

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

Uses a specific verb (Remove) with a specific resource (custom domain), which is clearly distinguishable from siblings such as railway_create_custom_domain, railway_delete_service_domain, and railway_delete_project. It stops short of clarifying whether the target is a project-scoped or service-scoped domain.

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

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

No statement of when to use this versus railway_delete_service_domain or the Supabase/Vercel domain-removal siblings, and no prerequisites or exclusions. The agent must infer usage purely from the tool name.

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, but the description adds meaningful context beyond the structured safety hints: it discloses the cascade effect (deployments are deleted) and the approval gate. It does not cover irreversibility or permissions fully, but it earns credit for exposing destruction scope and auth workflow.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the critical prerequisite. No filler, though the phrase 'BEON PASS' is unexplained and the description is very sparse given the tool's complexity.

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

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

With no output schema and 0% schema parameter descriptions, the description should compensate by explaining how to supply 'id', 'approval_id', and the several beon_* parameters. It mentions approval in passing but does not map it to 'approval_id' or clarify the other required context fields, leaving significant gaps for a destructive, multi-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 0% across 8 parameters, including required 'id' and UI-related fields like 'approval_id' and 'beon_context'. The description does not explain any parameter's meaning, format, or role, leaving the agent without semantic guidance.

Input schemas describe structure but not intent. Descriptions should explain 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 (Delete) and resource (environment), and clarifies that deployments are also removed. It does not explicitly differentiate from siblings like railway_delete_project or railway_delete_service, but the resource 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?

Only mentions the approval prerequisite ('Requires exact user approval in BEON PASS'). It gives no guidance on when to choose this tool versus alternatives, nor any exclusions or typical context for deletion.

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=false, so the safety profile is largely covered. The description adds real context beyond the annotations: the deletion is permanent and cascades to child resources, and it requires an out-of-band approval workflow. It does not, however, explain how the approval is obtained or how the approval_id parameter relates to that workflow.

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

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

Two tight sentences, zero filler, with the destructive scope front-loaded ahead of the approval prerequisite. Nothing to trim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 8-parameter tool with 0% schema coverage and no output schema, this is thin. The agent learns the operation is permanent and needs approval but cannot tell from the description how to populate the approval and BEON context parameters required to actually invoke it successfully.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 8 parameters, so the description carries the full explanatory burden and mostly fails it. It hints at the approval mechanism via 'exact user approval in BEON PASS', which loosely gestures at approval_id, but seven parameters (beon_app_id, beon_context, beon_resume_id, beon_release_id, beon_environment, beon_connection_id, approval_id) are left entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 (delete) and resource (project) plus the scope of impact ('and its resources'), which distinguishes it from railway_delete_service and railway_delete_environment. It stops short of explicitly naming those sibling alternatives, but the resource level alone makes the target unambiguous.

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

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

The description notes a prerequisite ('Requires exact user approval in BEON PASS') but offers no when-to-use guidance, no conditions that select this tool over the narrower delete_service/delete_environment siblings, and no warning about cascading deletions. Prerequisite information is present, but selection guidance is absent.

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=false and openWorldHint=true, so the safety profile is covered. The description earns credit by adding what gets destroyed (all deployments, i.e. a cascade) and the BEON PASS approval workflow, which annotations do not 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?

Two tight sentences, front-loaded with the action and its scope, followed by the gating requirement. Every clause carries information and there is no filler.

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

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

For a destructive 8-parameter tool with no output schema, the description covers purpose, cascade impact and the approval prerequisite adequately, and annotations carry the safety signal. It remains incomplete on the beon_* parameter family and on whether deletion is recoverable, leaving gaps for an agent to call it confidently.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 8 parameters, so the description must compensate and largely fails to do so. It alludes to an approval step that maps loosely to approval_id, but the required id and the six beon_* parameters are left entirely unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Delete a service') and adds the important scope detail that all deployments go with it. It does not explicitly contrast with siblings such as railway_delete_project or railway_delete_environment, so an agent must infer which deletion tool applies, but the cascade note already distinguishes it somewhat.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 one real precondition ('Requires exact user approval in BEON PASS'), which is actionable context for invoking the tool. However it offers no when-to-use framing, no alternatives for the non-destructive paths, and no signal that this is irreversible beyond the approval gate.

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, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only that the target is a 'generated' domain, which does not clarify what is destroyed, whether approval is required, or whether removal is reversible.

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

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

A single front-loaded sentence with no filler. It is appropriately sized, though its brevity reflects under-specification rather than disciplined editing.

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

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

For an 8-parameter destructive tool with no output schema, the description is too thin. It omits the approval workflow suggested by approval_id and says nothing about the beon_* context parameters an agent may need to supply.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 8 parameters, and the description explains none of them. It does not clarify that 'id' refers to the domain identifier, nor does it address approval_id or the beon_* plumbing parameters, so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain 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 (Remove) and resource (Railway generated public domain). The qualifier 'generated' implicitly distinguishes this from the sibling railway_delete_custom_domain, though that sibling is not named 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?

No indication of when to use this versus railway_delete_custom_domain, no prerequisites, and no mention of the approval flow implied by the approval_id parameter. The agent must infer usage entirely.

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 readOnlyHint=false, but the description goes further by disclosing the downstream consequence ('can trigger deployment and break applications') and a required approval gate. This is genuine added context beyond the annotations, though it doesn't explain what the approval flow returns or whether the delete is reversible.

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

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

Three short sentences, front-loaded with the action before the risk warnings. Every clause earns its place with no repetition of the name or 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?

Covers the two critical facts an agent needs (destructive consequence, approval gate), which is important given no output schema. But with 11 parameters undocumented in both schema and description, and no clarification of how approval_id/beon_context are supplied, the definition is not complete for correct invocation.

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

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

Schema description coverage is 0% across 11 parameters, so the description carries the burden and largely fails it: no parameter is named, and the required approval_id, projectId, environmentId, and name are never mapped to the stated approval requirement. Only an oblique hint ('requires exact user approval') gestures at the approval parameter.

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

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

States a specific verb and resource ('Delete a variable'), which is unambiguous and clearly the inverse of the sibling railway_set_variable. However, it does not explicitly name that sibling or the read counterpart (railway_list_variable_names), so differentiation is inferred rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 one hard precondition ('Requires exact user approval in BEON PASS') but no guidance on when to prefer this over updating a variable in place, nor which scope (environment vs service) to target. Usage context is implied rather than explained.

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=false, so safety is largely covered structurally. The description adds value by emphasizing permanence ('permanently destroy application data across environments'), but says nothing about auth requirements or the presence of an approval_id field, so the addition is modest.

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

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

Two short sentences, the destructive consequence front-loaded, with zero filler. Appropriately sized for the message it needs to convey.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 destructive mutation with no output schema, the description is thin: it omits parameter guidance, approval flow, and scope of impact beyond a general warning. Annotations cover the safety profile, but the rest of what 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 description coverage is 0% and the tool takes 9 parameters (only 2 required), yet the description explains none of them. It gives no hint about which identifiers are needed, nor what the approval_id and beon_* parameters are for.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Delete persistent storage'), and the name identifies it as a volume operation. However, it uses the loose phrase 'persistent storage' rather than naming the volume, and it does not distinguish itself from the sibling railway_delete_volume_backup, leaving a small ambiguity about exactly what gets deleted.

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

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

There is no guidance on when to use this versus alternatives (delete_volume_backup, restore_volume_backup) or when not to. No prerequisites, no mention that a backup exists or should be taken first, and no context on which volume/environment is affected.

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 destructiveHint=true and readOnlyHint=false annotations already tell the agent this is an irreversible write, so the bar is lower. The description's one contribution is the word 'permanently', which confirms non-recoverability but adds little beyond the annotation; it says nothing about the approval_id parameter's implied approval workflow, locked-backup behavior, or required permissions.

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

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

A single front-loaded sentence with no filler; the verb and the irreversible nature are stated first. It is efficient, though so terse that it borders on under-specification rather than crisp conciseness.

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

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

For a destructive, non-idempotent tool with 9 parameters, an unexplained approval_id, and no output schema, the description is far too thin. An agent cannot determine prerequisites (approval flow, locked backups), what identifiers are needed, or what happens on success from this text.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 9 parameters, so the description must compensate and does not. It never explains the difference between volumeInstanceId and volumeInstanceBackupId, nor the seven beon_* parameters (context, resume/release ids, environment enum, fixed connection id), leaving an agent guessing at what is required to invoke the tool.

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

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

States a specific verb and resource ('delete a volume backup'), which is unambiguous on its own. However, it does nothing to distinguish this from the several adjacent siblings such as railway_delete_volume, railway_lock_volume_backup, and railway_restore_volume_backup, all of which operate on the same volume-backup domain.

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

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

There is no when-to-use guidance, no named alternative (e.g. restore vs delete, or how to find a backup id via railway_list_volume_backups), and no preconditions such as whether a locked backup can be deleted. The agent is left to infer everything about context.

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=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: possible charges and a mandatory BEON PASS approval step, which tells the agent this is a gated, billable write. It still omits deployment lifecycle behavior (async completion, in-progress conflicts).

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

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

Three short sentences, zero filler, and the commit-selection scope is front-loaded before the cost and approval constraints. 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 10-parameter destructive mutation with no output schema, the description covers cost and approval prerequisites but leaves the bulk of the beon_* parameters and the return/result behavior undocumented. Adequate but with clear gaps.

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

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

Schema description coverage is 0% across 10 parameters, so the description must carry the load. It only clarifies commit selection (commitSha) and, indirectly via 'exact user approval', the approval_id/beon_* approval fields; the other parameters remain unexplained in both schema and 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?

States a specific verb (deploy) and resource (a service) plus the commit-selection scope, which distinguishes it from siblings like railway_restart_deployment, railway_rollback_deployment, and vercel_create_deployment. It does not explicitly name an alternative tool, 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?

The description implies the context (deploying a service) and states a precondition ('Requires exact user approval in BEON PASS'), which is genuinely useful routing information. However, it never says when to prefer this over restart_deployment or rollback_deployment, nor when-not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond that — no note on auth/connection requirements, no indication of what happens if no account is connected, and no behavioral context the annotations don't already 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?

A single front-loaded sentence with no filler or redundancy. It is tight, though the brevity edges into under-specification rather than deliberate economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 should say something about the shape of the returned identity (fields, scope, workspace/team association), and it does not. Combined with 0% parameter documentation, an agent knows the tool exists but not what it yields or when it is appropriate to call.

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

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

Schema description coverage is 0% across 7 parameters (approval_id, beon_app_id, beon_context, beon_resume_id, beon_release_id, beon_environment, beon_connection_id), and the description documents none of them. Although these look like platform-injected plumbing rather than user-facing inputs, the description provides zero compensation for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Identify the connected Railway user.' It is unambiguous about what the tool returns — the currently authenticated user — and no railway sibling overlaps with it. It does not, however, contrast itself with anything or scope the identity result, 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?

There is no guidance on when to call this versus alternatives, no prerequisites (e.g., must a Railway connection already exist?), and no mention of the closely named vercel_get_account sibling in the list. The agent is left to infer usage entirely from the name.

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 frames this as a read operation ("Read logs"), but the annotations declare readOnlyHint=false and idempotentHint=false, which directly contradict what a log-read tool should be. Although the description adds useful details about redaction and data sensitivity, the contradiction with structured annotations makes the behavioral profile unreliable.

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

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

The description is three short sentences with no obvious filler and front-loads the action. The phrase "after user review" is tersely ambiguous, but overall it avoids wasted words.

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

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

For a 9-parameter tool with no schema descriptions and no output schema, the description omits all parameter and return-value context. It offers only approval and redaction notes, which are insufficient for an agent to understand required inputs or expected output.

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

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

The input schema has 9 parameters with 0% description coverage, and the description does not mention any of them. It never explains that deploymentId is required, nor does it clarify the roles of limit, approval_id, or the beon_* fields, leaving the agent without enough information to invoke the tool correctly.

Input schemas describe structure but not intent. Descriptions should explain 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 says "Read logs" but never specifies that these are build logs, despite the tool name and the sibling railway_get_runtime_logs. The added context about user data and redaction is useful, but the core resource being read is left vague.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 prerequisite ("Requires exact user approval in BEON PASS") and mentions "after user review," but gives no guidance on when to choose this tool over railway_get_runtime_logs or any alternative. The agent is left to infer the build-log context entirely from the tool name.

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=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the vague phrase 'without unrestricted metadata,' which does not clarify what metadata is omitted, what permissions are required, or what the response contains.

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

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

The description is short and not padded, but the single sentence is under-specified and the trailing phrase 'without unrestricted metadata' is confusing rather than informative. It is concise but not effectively structured to help invocation.

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

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

For an 8-parameter tool with no output schema and zero parameter descriptions, the definition is not complete enough. Annotations cover read-only safety, but the description leaves key usage and parameter-meaning gaps that an agent would need 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?

There are 8 parameters with 0% schema description coverage, and the description mentions none of them—not the required 'id' nor the beon_* context parameters. With no descriptive compensation for the undocumented schema, an agent must infer all parameter meanings from names 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?

The description states a specific verb and resource: 'Inspect deployment status.' This is clearer than a tautology, but it does not distinguish the tool from siblings such as railway_list_deployments or railway_get_build_logs, and the phrase 'without unrestricted metadata' adds ambiguity rather than precision.

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

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

The description gives no explicit guidance on when to use this tool versus railway_list_deployments, railway_get_build_logs, or railway_get_runtime_logs. The required 'id' parameter implies fetching a specific deployment, but the description never states when this is the right choice.

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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds the useful scope that it inspects verification and certificate status, but it does not disclose return details, auth requirements, or any rate-limit behavior.

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

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

The description is a single front-loaded sentence with no filler. It is perhaps too terse for a 9-parameter tool, but it wastes no words.

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

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

For a tool with 9 parameters, 0% schema description coverage, and no output schema, the description is not complete enough to guide correct invocation. It gives purpose but leaves parameter meaning and optional context parameters undocumented.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 9 parameters, so the description must compensate but does not mention any parameter. The terms 'custom domain' and 'project' only weakly imply what id and projectId mean, and none of the optional beon_* parameters are explained.

Input schemas describe structure but not intent. Descriptions should explain 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 (inspect) and resource (custom domain verification and certificate status), which is clearer than a tautology. It does not explicitly distinguish this from sibling tools like railway_list_domains or domain verification tools from Supabase/Vercel, so it falls 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?

The description implies the tool is for checking domain status but gives no explicit guidance on when to use it versus railway_list_domains, railway_create_custom_domain, or sibling domain tools. It also omits prerequisites or when-not-to-use conditions.

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, openWorld, and non-destructive, so safety is covered. The description adds useful scoping context ('without variables') about what the response excludes, but does not describe return shape or pagination. Some added value beyond annotations, but not rich.

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

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

A single front-loaded sentence with no filler. It is efficient, though given the tool's 8-parameter complexity it could have spent a few more words productively on scope.

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

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

For a tool with 8 parameters, no output schema, and zero parameter descriptions, the description is too thin. It does not explain what 'configuration version' means, what is returned, or what the ancillary context parameters do.

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

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

There are 8 parameters (1 required) at 0% schema description coverage, so the description carries full burden but names none of them. 'Environment identity' loosely maps to environmentId, but the beon_* context parameters and enums are entirely undocumented in both schema and 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?

Specific verb ('Inspect') and resource ('environment identity and configuration version') make the operation clear. The qualifier 'without variables' distinguishes it from a fuller environment fetch, though it does not name a specific sibling tool. It is meaningfully clearer than a tautology but lacks explicit sibling differentiation.

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

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

The phrase 'without variables' implies a use case (fetching identity/config when variable data is not needed) but no explicit when/when-not guidance or named alternatives among siblings like railway_list_environments or railway_get_service_configuration. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description usefully discloses that the response includes the project's services and environments, but says nothing about the approval_id or beon_* parameters, which look like an authorization/context mechanism an agent would need to understand.

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

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

A single seven-word sentence, front-loaded with the verb and resource, with no filler. It is appropriately terse for a read tool, though the terseness leaves the parameter gap unaddressed.

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

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

For a tool with 8 parameters (including an approval_id that suggests a gated workflow) and no output schema, this description is too thin. It tells the agent what the call returns in broad strokes but nothing about the required/context inputs or the approval semantics.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 8 parameters, including six undocumented beon_*/approval_id fields, so the description carries the full burden and compensates with nothing. It never even clarifies that 'id' is the project identifier.

Input schemas describe structure but not intent. Descriptions should explain 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 (inspect) and resource (project) and adds the return scope: services and environments. It does not explicitly distinguish itself from nearby siblings like railway_get_service or railway_list_projects, so it falls 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?

No when-to-use guidance and no exclusions. An agent cannot tell from the text whether to call this versus railway_list_projects (discovery) or railway_get_service (per-service detail); only the verb 'get' implies the read-one-by-id pattern.

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 genuinely useful behavioral context beyond the annotations: log content may contain application data, known provider credentials are redacted, and an approval gate exists. It leaves a mild tension with readOnlyHint=false ("Read" implies a non-mutating op) unresolved, and says nothing about pagination or volume 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?

Three short, front-loaded clauses with no filler; the approval prerequisite and redaction guarantee are stated compactly. It is efficient, though slightly too terse to orient an agent on the 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?

For a 9-parameter, security-gated tool with no output schema and 0% schema coverage, the description covers the safety model but omits all parameter semantics and return/volume expectations, so an agent still lacks what it needs to invoke it correctly.

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

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

Schema description coverage is 0% across 9 parameters, and the description explains none of them. "User approval in BEON PASS" loosely gestures at approval_id but never names or maps it, and deploymentId, limit, and the beon_* fields are entirely undocumented.

Input schemas describe structure but not intent. Descriptions should explain 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 clear verb+resource ("Read logs") matching the tool name, so an agent can tell it retrieves log output. However, it does not distinguish this runtime-log tool from the sibling railway_get_build_logs, leaving the agent to infer the difference from the name alone.

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

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

"Read logs after user review" plus "Requires exact user approval in BEON PASS" gives a usable precondition (approval must exist before calling). There is no explicit when-to-use-vs-alternatives guidance against build logs or other read tools, so the routing is only implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond them — no auth/permission requirements, no note on whether the service must exist, no return-shape hint despite the absence of an 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?

A single front-loaded sentence with no filler, so it is not bloated. But it is under-specified rather than concise: the one clause does not earn its place by conveying enough information for reliable invocation.

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

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

For a tool with 8 parameters, 0% schema-coverage, no output schema, and no annotations gap to lean on, the description is inadequate. It omits parameter meaning, return content, and prerequisites, leaving the agent unable to call it correctly with confidence.

Complex tools with many parameters or behaviors need more documentation. 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 0% and the description never references any of the 8 parameters. The required 'id' is only obliquely hinted at by 'service identity', and the seven beon_* parameters (including a single-value enum connection id and an environment enum) are entirely opaque from both schema and 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?

States a resource ('service') and a rough intent ('inspect identity and project'), which is more specific than a bare name restatement. However, 'inspect' is a vague verb and it does not differentiate from the close sibling railway_get_service_configuration, nor does it indicate what identity/project data is returned.

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

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

No guidance on when to use this versus alternatives such as railway_get_service_configuration, railway_get_project, or railway_list_projects. The agent must infer usage purely from the name.

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 readOnlyHint/idempotentHint/destructiveHint already declared, the description's one addition is the explicit exclusion of environment variable values – a real data-disclosure trait not present in annotations. It still says nothing about what configuration is returned, whether secrets are redacted, or the response shape, so it adds only modest value.

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

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

A single front-loaded sentence with no filler; the exclusion is placed immediately after the verb phrase. It reads more as under-specification than tight conciseness, 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?

For a 9-parameter tool with no output schema and no parameter documentation, the description leaves too much unresolved: it does not define what 'configuration' covers, what the return looks like, or what the beon_* parameters are for. Annotations only carry the safety profile, so the description should do more of the explanatory work.

Complex tools with many parameters or behaviors need more documentation. 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 0% across 9 parameters, and the description mentions none of them. The two required IDs are self-evident by name, but the seven beon_* routing/context parameters (beon_app_id, beon_context, beon_connection_id, etc.) are completely unexplained in both schema and 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?

Specific verb ('Inspect') plus resource ('deployment configuration') with a scope qualifier that separates it from environment-variable tools. It does not name the closest siblings (railway_get_service, railway_get_environment_metadata, railway_configure_service), so an agent still has to infer which getter to pick, but the read-only inspection intent 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?

There is no when-to-use or when-not-to-use guidance. The clause about not returning environment variable values implies 'use something else if you need values' but names no alternative, and the description never explains its relationship to railway_configure_service or railway_get_service. An agent gets context but no 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 readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely useful non-obvious context: raw configuration and variable values are deliberately excluded from the return, which tells the agent what it will not see and prevents it from hunting for secret values in the output.

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

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

Two short sentences, zero waste, with the core purpose front-loaded and the return-value caveat following. Nothing to trim.

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

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

For an 8-parameter tool with no output schema and no parameter documentation anywhere, the description is too thin. It should at least explain what the beon_* parameters are for, what an approval_id selects, and how this relates to railway_commit_staged_changes.

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

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

Eight parameters with 0% schema description coverage and 0% description coverage — the required environmentId and seven optional beon_* fields are entirely undocumented in both places. Only two enums give partial hints (staging/production, a fixed connection id), so the description does not compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Inspect staged change metadata'), which is clear on its own. However, it does not name or distinguish itself from the sibling railway_commit_staged_changes, which is the natural alternative an agent must choose between.

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

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

No when-to-use guidance, no prerequisites, and no mention that committing is done via railway_commit_staged_changes. The agent must infer the inspect-vs-commit routing entirely from the tool names.

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