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

Annotations already declare openWorldHint, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds that a per-player authorization token is returned, but says nothing about what a repeat call for an already-authorized IP does, even though idempotency is asserted.

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, zero filler, with the action and the triggering scenario front-loaded before the return value. Nothing redundant with the title or schema.

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

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

For a small three-parameter mutation with annotations present, the description covers the action, the scenario, and the returned token (no output schema exists, so this is needed). Remaining gaps are error/repeat-call behavior against a non-existent or already-authorized player.

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?

user_ip and dry_run are fully documented in the schema; session_id has no schema description at all. The description partially compensates by stating the session must already exist and the IP is public, but adds no format or constraint detail. This matches a baseline 3 at 67% coverage.

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 (authorize) plus resource (relay session / player) and scope ('one more player... joining after the session was created'). This cleanly separates it from edgegap_create_relay_session, edgegap_get_relay_session, and edgegap_delete_relay_session in the sibling set.

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

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

Gives a clear usage condition: use it for a player joining after the session already exists, which implies create_relay_session handles players present at creation. It stops short of naming that sibling or stating exclusions such as duplicate authorization of an already-authorized IP.

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

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

Goes beyond the readOnly/idempotent annotations by disclosing that it validates the referenced application version and its ports, that no resource is created server-side, and that a manual dashboard upload is required. The runtime note that each match spins up an authoritative dedicated server is useful context, though the shape of the returned JSON 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 sentences, front-loaded with what is generated, followed by the manual-upload caveat and a closing rationale. No filler, though the final sentence about dedicated servers is context rather than call-critical.

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 13-parameter generator with no output schema, the description covers the essential contract: what it produces, what it verifies, and that creation happens outside the tool. It could go one step further in describing the returned artifact's contents, but the schema fills in the parameter-level detail.

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 85%, so the input schema already carries most parameter meaning (expansions, latency, ticket_expiration, CORS). The description only gestures at the parameter set at a high level (team count/size, optional latency rule, expansions) without adding format or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and artifact: "Generate a ready-to-upload Edgegap matchmaker JSON configuration with one profile." It immediately lists the scope (team count/size, latency rule, expansions), so an agent knows exactly what this produces and how it differs from the deploy/version siblings.

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

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

Explicitly says what the tool does NOT do and why ("Edgegap has no API for creating a matchmaker, so this tool does NOT create one"), then gives the required next step: save the config and upload via the dashboard. It also tells when to add expansions and when they are unnecessary.

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/openWorldHint/idempotent, and the description still adds real value beyond them: it discloses the conditional side effect ('makes no API call unless check_token is true') and the security guarantee ('never shows the token'). It also explains that failure paths return the reason and a fix, which is behavioral context the schema cannot express.

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

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

Front-loaded with the primary resource (which API/version/mode), then guardrails, then the token note, then the call conditions. Dense but every clause carries information; the long guardrail list in the first sentence is the only mild bloat.

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 an output schema, full annotation coverage, and 100% parameter description coverage, the description supplies everything an agent needs: what it returns conceptually, when to call it, cost implications, and the token non-disclosure guarantee.

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

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

Schema coverage is 100% and the single parameter already documents the one-read-only-call behavior. The description's 'makes no API call unless check_token is true' reinforces but does not extend the schema, so the baseline 3 applies.

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

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

States a specific verb ('Report') and enumerates exactly what is reported: API target, version, local vs hosted, guardrails, and token usability. No sibling tool does anything similar, so 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?

Gives three explicit trigger conditions: 'call it first when unsure what this session is allowed to do', 'before anything billable', and 'when tool calls fail with a token problem'. That is a clear when-to-use rule with concrete situations rather than vague advice.

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 openWorldHint, non-idempotent, non-destructive, but say nothing about side effects. The description adds real behavioral value by clarifying that creation 'does not deploy anything' and must be followed by edgegap_create_app_version, preventing a common misunderstanding. It does not cover auth requirements or what happens to the name if it already exists, 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 tight sentences: the action first, the precondition second, the follow-up step third. No repetition of schema or title content and nothing extraneous.

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, an agent still learns the logical next call, which partially compensates. The remaining gap is that the description never indicates what is returned (e.g. whether an application ID comes back for use in edgegap_create_app_version), though the chained-tool guidance makes the call sequence unambiguous.

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

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

Schema coverage is 100% and the parameter descriptions (name constraints, dry_run semantics, is_active default) are already richer than anything the description offers. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a new application') and immediately clarifies what an application is ('to hold game server versions'), distinguishing it from version-creation and deployment siblings. An agent can identify it without opening the schema.

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

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

Gives an explicit precondition ('Only call this after edgegap_list_apps confirms no suitable application exists') naming the alternative tool and the condition that selects it, plus the required follow-up step (edgegap_create_app_version). Both when-to-use and what-comes-next are covered.

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

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

With annotations only covering openWorld/idempotent/destructive, the description adds substantial operational detail: refusals happen 'with nothing sent' for 'latest'/empty tags and malformed docker_image, secret-named env vars are masked in the dashboard, and the 'This value is set and encrypted' placeholder is rejected. That tells the agent exactly what will silently fail before a billable call is made.

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

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

Front-loaded with the core action, then prerequisites, then constraints and refusals — a logical order for a call-plan. It is dense and slightly over-packed in the middle (resource units, verify_image, tag refusal, env masking all in successive clauses), but almost every sentence carries a distinct constraint that isn't duplicated in structured fields.

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 15-parameter mutation with 8 required fields, no output schema and no enums, the description covers the prerequisites, the validation rules, the failure modes and the secret-handling caveat. An agent can construct a correct first call and anticipate the main rejections without further reference.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds value the schema doesn't: the cpu-unit/memory relationship is restated as a hard constraint, docker_tag must be a build ID for reproducibility, and copying secrets fails on purpose. It does not mention several parameters (env structure, ports, endpoint_storage, max_duration_minutes) beyond the schema's own text.

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

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

Opens with a specific verb+resource: 'Register a container image as a deployable version of an application.' That is clearly distinct from sibling tools like edgegap_update_app_version, edgegap_get_app_version and edgegap_list_app_versions; an agent knows this is the create path.

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

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

Gives concrete routing context — 'see edgegap_get_registry_credentials and edgegap_list_registry_tags' for the image prerequisite, and tells the agent when to set verify_image true ('on the first version'). It never states the inverse (don't use this to modify an existing version; use update_app_version), so the exclusion against the closest sibling is left implicit.

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

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

Annotations only declare openWorldHint/idempotentHint/destructiveHint; the description adds genuinely new behavior: the secret key is transmitted once and never echoed back, and credentials must be scoped to the bucket rather than reused. It still doesn't say what the call returns or whether a partial failure leaves registered storage behind.

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, zero filler, ordered as purpose → credential constraint → next step. The security-critical 'never invent or reuse other credentials' line is placed before the activation instruction, which is where an agent should hit it.

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

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

Covers what to supply, what not to supply, and how to activate log export afterwards — enough for an 8-parameter mutation tool with no output schema. The remaining gap is the return value (e.g. a storage ID or name to reference in update_app_version), which the absence of an output schema leaves unaddressed.

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

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

Schema coverage is 100%, so the schema already documents all eight parameters including the enums for output_format and container_log_version. The description only reinforces credential semantics (bucket-scoped key pair) and never touches dry_run, output_format or container_log_version, so the baseline 3 applies.

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

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

States a specific verb ('Register') and resource (an S3-compatible bucket as Endpoint Storage) and immediately explains the payoff: container logs exported there at deployment end. That scope plus the named provider examples clearly separates it from edgegap_list_endpoint_storage, edgegap_delete_endpoint_storage and edgegap_create_pull_profile.

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 the operational prerequisites (developer-supplied bucket, endpoint URL, bucket-scoped key pair, never the Edgegap API token) and the follow-up step: set endpoint_storage on the version via edgegap_update_app_version. It doesn't state when not to use this tool, e.g. reuse of existing storage or rotation flow, so it falls short of a 5.

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

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

Annotations declare openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is already covered. The description adds genuinely non-redundant behavior: the profile is inert until linked, and destination collisions with image paths should be avoided. It stops short of saying what a successful call returns or how duplicate names are handled, which matters for a non-idempotent create.

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 clauses, front-loaded with the verb and the mechanism, followed by the lifecycle dependency and the one operational caution. No filler and nothing repeated from the schema.

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

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

For a 6-parameter create with full schema coverage and no output schema, the description covers the two things an agent can't infer structurally: the profile is inert until linked, and destination paths can shadow image content. Only the return value / how to reference the created profile for linking is left implicit.

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

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

Schema description coverage is 100%, so every parameter (including source path syntax, source_type enum, and dry_run) is already documented at the field level. The description only adds the destination-collision caveat, which is marginal extra meaning. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('Create a pull profile') and immediately explains the mechanism: at boot, files are copied from an Endpoint Storage bucket into the container. The parenthetical use-case examples (maps, configs, large assets kept out of the image) make the concept unmistakable and differentiate it from the storage-creation siblings.

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

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

It states the key prerequisite explicitly: the profile 'does nothing until linked to a version with edgegap_link_pull_profile', which routes the agent to the follow-up tool. It also adds a caution ('Avoid destination paths the image already uses'). What it lacks is guidance relative to edgegap_create_endpoint_storage (must that exist first?) or when to prefer baking files into the image 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 only give the openWorld/idempotent/destructive profile; the description adds genuinely new behavioral context: relay sessions are billed while open, the call blocks until ready, the host is created first, and it returns the relay address plus per-player authorization tokens. The security caveats (host can cheat, host latency advantage, match dies if host quits) further explain the operational consequences of choosing this path.

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?

Efficient in substance — every sentence is decision-relevant — but the action itself is deferred behind two long admonition paragraphs, and the 'not the default' warning is repeated in both the opening and the 'Only use this when' sentence. Slightly wordier than needed, though justified by the misuse risk.

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

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

With no output schema, the description still explains the return value (relay address + per-player tokens) and the async readiness behavior. It also covers billing, cleanup via edgegap_delete_relay_session, and late-joiner handling, so an agent has everything needed to call and manage the session correctly.

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

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

Schema description coverage is 100%, so the schema already documents user_ips, webhook_url, timeout_seconds, wait_until_ready, and dry_run. The description reinforces the host-first ordering and mentions per-player tokens but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Creates an Edgegap relay session') and immediately distinguishes it from the sibling edgegap_deploy by naming the dedicated-server alternative. It also names edgegap_authorize_relay_user and edgegap_delete_relay_session, so an agent can place it precisely in the relay workflow without opening a schema.

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

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

Explicitly states when to use it ('developer has chosen peer-to-peer/host-client', listen-server netcode) and when not ('not the recommended default', 'Never pick it only because it needs no server image'), names the preferred alternative (edgegap_deploy), and adds a fallback instruction to ask first if the netcode hasn't been established.

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 and idempotentHint, and the description adds materially beyond them: irreversibility ('Cannot be undone'), the blast radius (all versions, but registry images untouched), and the two guard conditions that cause failure. This is exactly the context an agent needs before a destructive call.

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

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

Effectively one dense, front-loaded sentence with zero filler, but the parenthetical remedy clause makes it slightly hard to scan. Every clause still carries information, so it is close to optimal despite the 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?

For a destructive 3-parameter tool with no output schema, the description covers scope, prerequisites, failure modes, side-effect boundaries, and irreversibility. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by explaining the semantics of max_versions (default 0 means refuse if any versions exist, with the two remedies) and stressing that application must be an exact name. dry_run is left to its own schema description, hence not a 5.

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

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

States a specific verb (delete) and resource (one application plus every version under it) and frames the intent (clean up a test application). It is clearly distinguished from the sibling edgegap_delete_app_version, which is named as the narrower alternative.

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

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

Gives explicit preconditions and refusal conditions: refused while any deployment is running, and refused when versions exceed max_versions. It names the alternative tool (edgegap_delete_app_version) and the escalation path (raise max_versions after developer agreement), so the agent knows exactly what to do when blocked.

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

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

Annotations already mark it destructive/idempotent/openWorld, but the description adds real value beyond them: the running-deployment refusal, that the image is retained in the registry, and that the action is irreversible requiring confirmation. These are operational traits not encoded in annotations.

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

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

Front-loads the action and scope, then layers in the refusal condition, alternative, and irreversibility. Every sentence carries information; 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?

No output schema exists, but the description covers safety, refusal behavior, and consequence of deletion thoroughly enough for a destructive single-target operation. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so both required parameters and their meanings are already documented. The description's 'Exactly one exact version name' reinforces the version parameter's exactness but adds little beyond what the schema states.

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

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

States a specific verb and resource ('Delete one version of an application') and scopes it to a single exact version. It distinguishes itself from siblings by explicitly naming edgegap_delete_registry_tag for the image and implying it differs from delete_app.

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 the use case ('clean up test versions'), an explicit refusal condition ('refused while any deployment of that version is running'), and routes the agent to the alternative for the container image. Confirmation guidance when the version wasn't created in-conversation adds clear when-to-be-cautious direction.

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

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

Annotations already flag destructive/idempotent/openWorld, but the description goes further: it discloses the refusal guard, the cascade effect that exporting versions stop exporting, that the bucket and existing logs survive, and that the operation is irreversible. That is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the verb and the primary target, and every sentence carries operational content with no filler. The middle sentences are dense and slightly clause-heavy, which costs a point on readability but not on usefulness.

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

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

For a 3-parameter destructive tool with no output schema, it covers the guard conditions, side effects, irreversibility, escalation path, and the safety valve (dry_run is documented in the schema). Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the name must be an exact single name, and max_pull_profiles carries a coupled semantics (profiles go with the storage; default 0 blocks deletion). It does not spend words repeating dry_run, which the schema already explains well.

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 one Endpoint Storage') plus the intended scenario ('to clean up a test one'). It also contrasts with edgegap_list_endpoint_storage / create siblings implicitly by being the removal counterpart and names edgegap_delete_pull_profile as a different action, so an agent can place it precisely.

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

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

Explicitly gives the preconditions and the fallback paths: refused when pull profiles exceed max_pull_profiles, then either delete them with edgegap_delete_pull_profile or raise the threshold 'after the developer agreed'. It also says when to confirm with the developer before deleting a storage this conversation did not create.

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

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

Goes well past the destructiveHint/idempotentHint annotations by disclosing the cascade effect (every linked version stops getting its files at boot), an API blind spot (linked versions cannot be listed), and what is explicitly left intact (the bucket and its files). That is exactly the risk information an agent needs before a destructive call.

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

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

Front-loads the action and scope, then layers consequences and caveats; nearly every clause carries information. The parenthetical about the API's inability to list links is dense but justified. Minor redundancy between "Cannot be undone" and the destructive annotation.

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 3-parameter tool with no output schema, the description covers side effects, irreversibility, and a safety precondition, leaving only the response shape unstated. Little else an agent needs is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented, including the dry_run escape hatch. The description only reinforces that the name is exact and singular ("Exactly one exact name"), which the schema already states, so it adds little beyond 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 ("Delete one pull profile from an Endpoint Storage") and implicitly carves itself out from edgegap_delete_endpoint_storage by noting "The bucket and its files are not touched." It does not name sibling tools explicitly, but the scope 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?

Gives a clear context ("to clean up a test profile") and a concrete prerequisite caveat: consult the developer when the profile was not created in this conversation, because the API cannot list links. It stops short of naming an alternative tool or a when-not-to-use rule beyond that caveat.

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 and idempotentHint, but the description adds what is actually destroyed (the tag and its underlying image), that deletion is irreversible, and the downstream consequence that versions pinned to the tag can no longer start deployments. That is substantive context beyond the safety flags.

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

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

What-it-does and scope lead, followed by input constraints, then the pre-check and irreversibility warning. Four dense sentences with no filler or repetition of schema content.

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, three-parameter tool with no output schema, the description supplies the consequence of deletion, the rejection rules, and the recommended pre-verification step. Nothing an agent needs to avoid a bad call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by constraining values to exactly one image name and one exact tag, rejecting wildcards/lists/"latest". It stops short of documenting dry_run or the naming format, which the schema handles 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 ("Delete one tag, and the image it points to") scoped to this organization's registry, and names the operational goal ("clean up old builds"). Clearly distinguishable from sibling edgegap_list_registry_tags, which the schema even cross-references.

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

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

Gives an explicit precondition ("check edgegap_list_app_versions first"), enumerates what will be refused (wildcards, lists, "latest", bulk delete), and states the intended use case. An agent knows both when to call it and what inputs will fail.

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 and idempotentHint, but the description adds the human-facing consequence - connected players lose their relay connection - which is not derivable from annotations. It also documents input validation behavior (empty IDs, wildcards and lists refused), useful operational 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?

Four short sentences, front-loaded with the action and its blast radius, then the cleanup rule, then the input constraint. Every sentence carries information; only the imperative cleanup guidance borders on advisory rather than definitional.

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 no-output-schema destructive delete, the description supplies impact, scope, validation, and the dry_run escape hatch is documented in the schema itself. Nothing essential is missing, though return/error behavior is left implicit.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds a real constraint - exactly one session_id, wildcards and lists refused - that tightens interpretation of the single string parameter beyond the schema's per-parameter wording.

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 (close/delete) and resource (relay session) with explicit single-item scope, which cleanly separates it from the get_relay_session, create_relay_session, and authorize_relay_user siblings.

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

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

Gives a concrete when-to-use rule (delete every test session you created before ending your task), which is real workflow guidance. It stops short of naming alternatives or stating when-not to use, so it is clear context rather than full routing guidance.

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

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

Goes well beyond the annotations: discloses the async return (request_id, no connection details yet), the auto 'edgegap-mcp' tag, lifecycle (runs until stopped or max_duration), billing implications, secret-env-var hiding, and multiple refusal conditions (token in env, 'latest' docker tag, concurrent-deploy caps, max_duration limits, local per-run cap). This is unusually rich behavioral context.

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

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

Front-loads purpose and the async/next-step behavior before restrictions. It is dense and long, but for a 14-parameter tool with many guardrails most sentences earn their place; a slight trim of the restriction run-on 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?

Output schema exists, so it needn't explain return structure, and the description still covers the immediate return (request_id) and next-step tool. Given complexity, annotations, and schema richness, nothing critical is missing 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 coverage is 100% so the schema already documents all 14 params, but the description adds real meaning: webhooks as a polling alternative, require_cached_locations for faster starts, private_host_ids placement order, and secret-env-var hiding. It complements rather than repeats the schema.

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

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

States a specific verb and resource ('Start one authoritative dedicated game server from an application version') and clarifies placement near specified players. The distinction from hosting-vs-player-hosted is clear, and it is easy to tell apart from relay/session siblings.

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

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

Explicitly frames this as 'the recommended way to host a multiplayer match' and directs the next step ('Follow this call with edgegap_wait_for_deployment'). It also adds operational guidance ('Always stop deployments you started for testing') and names the tool that finds these deployments.

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/closed-world, but the description adds substantial behavior beyond them: engine-specific quirks (Unreal refuses root, Unity -batchmode -nographics, Godot --headless), CRLF fixing, and the assumption-listing contract for omitted parameters. It also states 'Makes no API calls' and that output is validated before return, which an agent needs to trust the result.

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

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

Front-loaded with verb+artifact before the detail, and every clause is informational rather than filler. The primary sentence is an unusually long run-on list of generated content, which slightly hurts scanability but not correctness.

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 trigger, prerequisites, assumption handling, downstream validation and the fact that no API is called, which is thorough for a 7-parameter generation tool with no output schema. It does not explicitly state the returned payload shape or overwrite behavior if a Dockerfile already exists, a minor residual gap.

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

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

Schema coverage is 100%, so the schema documents defaults, enums and ranges for all seven parameters. The description still adds value by explaining the assumption mechanism for omitted values (they are assumed and surfaced for confirmation), which changes how an agent should treat partial input rather than just what the fields mean.

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 artifact (write a Dockerfile) for a defined resource (this project's headless game server build) and enumerates concrete content it will produce. It explicitly names a sibling, edgegap_validate_server_config, which the output is checked against, so an agent can place it relative to the rest of the toolset without opening schemas.

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

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

Gives an explicit trigger and preconditions: 'Call this when the project has no Dockerfile, before building anything,' plus a preceding step ('Look at the build output first so you can pass the real build folder...'). It also routes the follow-up ('Write the result to Dockerfile, then build') and names the validation sibling, leaving little to inference.

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

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

Annotations already cover read-only and open-world hints, so the description's added value is the disclosure that env var values are never returned — a meaningful safety/redaction detail an agent needs. It also scopes the read ('one version in full'), though it says nothing about rate limits or error 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 sentences, zero filler. The payload contents come first and the usage cue comes second, so the most selection-relevant information is 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?

An output schema exists, so the field enumeration is partly redundant, but it usefully doubles as a selection aid. Safety is covered by annotations and the env-var redaction note. Nothing critical is missing, though it could note that this is the only way to inspect a single version's config.

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

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

Schema description coverage is 100%, with both 'application' and 'version' documented, including a pointer to edgegap_list_app_versions for valid version names. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

Opens with a specific verb and resource ('Read one version in full') and then enumerates exactly what is returned: image, resources, ports, max_duration, cache flags, restart policy, Endpoint Storage, env var names. That enumeration distinguishes it cleanly from edgegap_list_app_versions and edgegap_create_app_version without needing the schema.

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

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

Explicitly states when to reach for it: 'Use it before edgegap_update_app_version or edgegap_deploy to check what a version will do.' That names the downstream siblings and the decision point. It stops short of stating exclusions (e.g., 'use list_app_versions to browse'), so it is a strong 4 rather than 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?

The annotations already confirm it is a read-only operation (readOnlyHint: true). The description adds behavioral context by stating that the status is delivered only 'once it is ready' and detailing the data returned (connection address and ports), which enhances transparency.

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

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

The definition is highly concise, using two short, impactful sentences. The most crucial information—the operational constraint and the sibling tool recommendation—is 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?

The description covers the operational lifecycle of the tool, explaining both what the tool provides (status, ports) and how it should be used in practice (avoid manual loops). Given the high schema coverage, this provides maximum value without redundancy.

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 coverage is 100%, providing a solid baseline. The description does not add unique semantic meaning to the required 'request_id' beyond its role in retrieving status, but it frames the context of that ID perfectly.

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 precisely states that the tool reads the 'current status' of a deployment, specifying that it includes connection address and ports. By mentioning 'one deployment,' it defines the scope, and it clearly sets this tool apart from the waiting tool.

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

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

It provides extremely clear usage guidance by advising against manual polling loops. It explicitly recommends the alternative tool, edgegap_wait_for_deployment, for newly created deployments, effectively directing the agent on the optimal call 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 readOnlyHint and openWorldHint annotations already cover the safety profile, and the description adds valuable context about crash output and retention for stopped deployments. It does not contradict the annotations and adds operational insight beyond them.

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, followed by usage guidance and a retention caveat. Every sentence adds useful information without 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 two-parameter read-only log retrieval tool with full schema coverage and annotation safety hints, the description is complete enough. It covers purpose, when to call it, output content, and the stopped-deployment retention caveat.

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

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

Schema description coverage is 100%, so request_id and max_characters are already documented. The description adds little parameter-specific meaning beyond saying it retrieves deployment logs, which makes the baseline 3 appropriate.

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

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

The description states a specific verb and resource: retrieving stdout/stderr and crash output for a deployment. It clearly distinguishes the tool's content from generic deployment lookup siblings, though it does not explicitly name when to use it instead of edgegap_get_deployment or edgegap_get_deployment_metrics.

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

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

It gives a clear trigger: call this whenever a deployment errors or a server exits unexpectedly. The rationale about crash exit codes is useful, but it does not mention explicit alternatives or 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 and openWorldHint=true, so safety is covered; the description adds real value by stating the return shape (latest/average/peak with the API's own labels) and the default window (whole life of the deployment). It omits any note on data availability/retention or rate limits, which is the remaining gap.

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

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

Two sentences, zero filler: the first front-loads what the response contains, the second gives use cases and the default window. Every clause earns its place and the most decision-relevant information comes first.

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 an output schema present and read-only annotations, the description need only frame intent and scope, which it largely does, including the default window and metric shape. It could add one line on when metrics become available for a deployment or on step-size tradeoffs, but nothing critical is missing.

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

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

Schema description coverage is 100%, so step, start_time, end_time and request_id are already fully documented in the schema. The description only restates the default time window, adding no syntax or format detail beyond what the schema says; baseline 3 is appropriate.

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

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

Specific verb ("Summarise") plus resource ("a deployment's resource use over time") and an enumeration of the exact signals returned: CPU, CPU throttling, memory, network, each as latest/average/peak. This clearly separates it from sibling reads like edgegap_get_deployment, edgegap_get_deployment_logs, and edgegap_wait_for_deployment.

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

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

Gives two concrete motivating scenarios: sizing a version (cpu_units, memory_mb) from a real match, and diagnosing whether a crash was memory or CPU starvation before redeploying. It stops short of naming the sibling alternative (logs) that would pair with the crash-diagnosis case, so there is no explicit when-not guidance.

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

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

Goes well beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): discloses that credentials are only available with the quick-start token, that a regular API token returns steps instead and should not be retried, that the returned token is registry-scoped, and how to handle it securely (--password-stdin, not in files).

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

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

Front-loaded with purpose and immediate usage condition. Every sentence adds actionable context (auth caveat, token handling, validation step, alternative registries) without redundancy.

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

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

Given the tool's complexity (token scoping, conditional availability, security-sensitive handling) and absence of an output schema, the description covers all critical operational details an agent needs to call it correctly and handle the result.

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

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

Schema coverage is 100%, so the schema already documents 'tag' and 'image_name' fully. The description adds no parameter-specific syntax or meaning beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb (Get) and resource (push login for the private Edgegap container registry), including the registry domain. Distinguishes from siblings like edgegap_list_registry_tags and edgegap_create_app_version by focusing on credential retrieval for image push.

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

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

Explicitly says when to use: 'Use this when the server image is not in a registry yet.' Also names alternatives and exclusions: if using Docker Hub, GHCR, ECR, or GitLab, skip this tool and pass the registry to edgegap_create_app_version. Guides to call edgegap_validate_server_config before building.

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 and openWorldHint, so safety is covered. The description adds genuinely useful behavioral context: what data comes back (readiness flag, relay address, ports, per-player authorization tokens). It does not cover auth requirements or rate limits, so it stops short of a 5.

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

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

Two sentences, zero filler: the first front-loads the return contents, the second handles routing against the sibling tool. 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?

With no output schema, the description carries the burden of describing return values and does so concretely. Combined with annotations and a fully documented single parameter, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100% and the single session_id parameter is documented in the schema as 'Returned by edgegap_create_relay_session.' The description adds no format or syntax detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('one relay session') and enumerates what the read returns: readiness, relay address and ports, authorized players with tokens. It is clearly distinguishable from edgegap_create_relay_session by name.

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

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

Explicitly says create already waits for readiness, and directs the agent here to re-read a session or read one created with wait_until_ready false. That is a concrete when-to-use rule with the alternative named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and the description reinforces this with "No API call", clarifying that this is a local content fetch rather than a remote Edgegap request. It also discloses the default resolution behavior (SKILL.md when file is omitted) and the incremental-fetch pattern. It stops short of saying what happens with an unknown skill or file name (error vs. empty), which is the one behavioral gap.

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

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

Front-loaded with what the tool returns, then the selection rule, then the progressive-fetch instruction; no sentence is filler. The nested parenthetical about server instructions and edgegap_list_skills is slightly dense but carries real routing information.

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

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

With no output schema, the description carries the return-value burden and does so: the agent knows it receives SKILL.md workflow content or a named reference/template. For a two-parameter read tool this is essentially complete, with only failure-mode behavior left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine selection guidance beyond the field types: which skill to pick, what to do when unsure, and that file is used to reach reference/template documents the SKILL.md points to. That converts the schema's enumerated names into an actionable selection policy.

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?

"Load one Edgegap agent skill: its SKILL.md ... or one of its reference documents or templates with file" names a specific verb (load), a specific resource (skill file), and the two modes of the call. It is cleanly separable from edgegap_list_skills (enumeration) and edgegap_update_skills (mutation) without opening either schema.

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

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

Explicit sequencing: "Load the skill that matches the project before acting", with the selection authority named (server instructions and edgegap_list_skills) and a concrete fallback ("edgegap" when unsure). It also says to fetch references and templates only as you reach them, which tells the agent how to descend the skill tree rather than dumping everything up front.

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 a genuine behavioral trait beyond the annotations: running deployments are unaffected, only new ones pick up the bucket files. This is exactly the kind of side-effect information annotations (idempotent, non-destructive, open-world) cannot convey. It doesn't cover auth requirements or what happens on a duplicate link, so not a 5.

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

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

A single sentence with the primary action front-loaded, the inverse operation parenthesized, and the side-effect caveat last. No 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?

No output schema exists, but the description covers purpose, the unlink variant, and the deployment-timing behavior, which is what an agent needs to call it correctly. Minor gaps: behavior on an already-linked profile and error modes are unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including `unlink` and `dry_run`. The description restates `unlink: true` but adds no syntax, format, or validation detail beyond the schema, putting it at 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 (link/unlink) and resource (pull profile ↔ application version) and explains the functional consequence: new deployments get bucket files at boot. No sibling tool performs linking, so it is inherently distinct, though the description doesn't name alternatives.

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

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

Explicitly explains how to trigger the inverse operation via `unlink: true`, which is the main usage branch for this tool. Lacks explicit when-to-use context (e.g. link profiles only after the profile and version both exist), but the operational guidance is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the organizational scope (whole org, no filtering) which is useful, but says nothing about pagination behavior or result volume, which matters for a list tool.

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

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

Three short sentences, front-loaded with the action, then workflow guidance, then a definition. Every sentence earns its place with no filler.

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

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

Output schema exists so return values need no explanation, and the tool is a simple read. The only real gap is pagination/parameter behavior, which lowers it from a 5 for a tool that returns potentially large org-wide lists.

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 50%: 'limit' is documented, but 'page' has no description anywhere. The description adds no parameter guidance at all—no mention of paging, default page size, or how to iterate results—so it fails to compensate for the 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 (List) and resource (applications in the Edgegap organization), and additionally defines what an 'application' is versus the sibling version tools: 'groups versions of one game server'. An agent can distinguish this from edgegap_list_app_versions without opening either schema.

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

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

'Start here before creating or deploying anything, so you reuse an existing application instead of making a duplicate' gives a clear precondition and intent, effectively routing the agent away from edgegap_create_app. It stops short of naming the sibling explicitly or saying when not to call 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 and openWorldHint, and the description adds substantial context beyond them: registry logins and secret env values are never returned, the API substitutes the literal string "This value is set and encrypted", and the agent is told where to get the real values (dashboard Container Registry page or the developer). That is exactly the kind of behavioral caveat that prevents dead-end calls.

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 returned fields and the deploy-readiness workflow are front-loaded, and the secret-redaction caveat follows logically. The WebGL/wss parenthetical about TLS Upgrade is informative but slightly more detail than an agent needs to select the tool.

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

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

This is a single-parameter read tool with an output schema, so return values need no explanation — yet the description still flags which returned fields matter and which are redacted. Nothing needed to call it correctly or interpret the response is missing.

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

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

There is only one parameter and schema coverage is 100%, with the schema itself noting it is the application name as returned by edgegap_list_apps. The description adds nothing further about the parameter (no format, casing, or lookup caveats), so the schema carries the full load — the baseline 3 for high coverage applies.

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

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

States a specific verb and resource ('List the versions under an application') and enumerates what each entry contains (image, resources, ports, TLS Upgrade flag, registry-login status), which clearly separates it from edgegap_get_app_version's single-version read. It never names the sibling tools explicitly, so the list-vs-get distinction 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 three concrete usage scenarios: finding the version name to deploy, checking a version is ready before deploying, and copying non-secret settings when creating a new version — the last effectively routes to edgegap_create_app_version. No explicit 'don't use this when...' or named alternative (e.g., get_app_version for a single known version) is provided.

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 and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the cost/orphan risk and the equivalence of only_agent_deployments to a tags filter (with a note about versions up to 0.3.3). It could still say more about pagination limits beyond the schema, but this is strong.

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

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

Purpose and when-to-use are front-loaded, and every sentence carries constraint information. It is dense and the operator rules run long, but little is wasted. Slightly sprawling for a single paragraph.

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?

An output schema exists, so return values need not be explained. All four parameters, their interactions, and the usage context are covered adequately. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds substantial meaning the schema does not: which operators apply per field, ilike only on fleet_name/host_name, in/nin requiring array values, created_at restricted to eq/gte/lte, and the one-filter-per-field constraint. This is genuinely additive.

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

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

States a specific verb and resource (list active deployments) plus scoping (optionally filtered and sorted). An agent can immediately distinguish this from edgegap_get_deployment (single) and edgegap_deploy (create). The scope is precise.

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

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

Explicitly names the use case: find deployments left running from earlier sessions before starting new ones, warning that orphaned servers cost money. It also gives a targeted mode (only_agent_deployments) for agent-started deployments, effectively directing the agent when to use which variant.

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

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

Read-only and open-world behavior are already covered by annotations, and the description adds meaningful context beyond them: it explains what endpoint storage is for, that pull profiles copy files at container boot, and that secret keys are never returned. It does not cover pagination or response shape, but the security and domain behavior disclosure is strong.

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

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

The description is front-loaded with the core purpose and then briefly explains the two resource types, security handling, and related tools. Every sentence contributes useful context without repetition or 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 zero-parameter, read-only list tool with no output schema, the description provides enough domain context about what is listed, the relationship between buckets and pull profiles, and the security constraint around secret keys. An agent can confidently select and invoke it.

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

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

The tool has zero parameters, so there is no parameter semantics to document and the baseline is 4. The description does not need to compensate for missing schema coverage.

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, 'List', and precisely defines the two resources returned: Endpoint Storage buckets and the pull profiles under each. It explains the domain concepts well enough that an agent can distinguish this read operation from sibling create/delete/link 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?

It gives useful context by explaining that endpoint storage is attached via edgegap_create_app_version / edgegap_update_app_version and pull profiles via edgegap_link_pull_profile, which helps the agent understand where this listing fits. However, it does not explicitly say when to call this tool versus alternatives, nor does it state exclusions such as 'use this before linking' or 'this does not create resources'.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds genuinely useful behavior: status filtering semantics ('only ACTIVE hosts accept deployments') and the failure mode for orgs without fleets. It stops short of describing pagination or the shape/ordering of the returned host list, which keeps it from a 5.

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

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

Four short sentences, front-loaded with the core action, followed by the operational constraint, the downstream call, and the error case. Nothing is repeated and every sentence carries information an agent needs.

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

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

No output schema exists, but the description names the returned fields (status, IP, location), the key filtering concept, the hand-off to edgegap_deploy, and the failure condition. For a single-parameter read tool this is sufficient 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 is only one parameter (fleet_name) and schema coverage is 100%, with the schema already saying it is 'the private fleet name, as shown in the dashboard.' The description refers to 'one of the organization's private fleets' but adds no format, naming convention, or lookup guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb (list) and resource (hosts of a private fleet) and immediately clarifies what a private fleet is ('dedicated machines Edgegap manages for you'), plus the fields returned (status, IP, location). No sibling tool covers fleet hosts, so there is no ambiguity to resolve.

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

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

Explicitly says only ACTIVE hosts accept deployments, tells the agent to pass host_id values to edgegap_deploy as private_host_ids, and warns that organizations without private fleets get an API error. That is when-to-use, what-to-do-next, and a when-not condition all in one paragraph.

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 and openWorldHint, so safety is covered. The description adds one genuinely useful behavioral fact — the filtered result reflects capacity "right now," i.e. volatile data — but says nothing about pagination, result volume, or ordering, which matters for a list endpoint that can span many cities.

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 the filtering behavior, then the sibling pointer. No filler or restatement of the tool name.

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?

An output schema exists so return shape needn't be explained, and there are no required parameters to warn about. The only real omission is pagination behavior for a potentially long list, which the description never addresses.

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

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

Schema coverage is 50%; application and version are documented in-schema and the description restates that pairing as a capacity filter, adding a little semantic value. page and limit get no mention in the description, and with the schema silent on page, half the parameter surface is explained in neither place.

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

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

States a specific verb and resource — "List the cities Edgegap can deploy to" — and immediately clarifies that passing application+version narrows the result to locations with current capacity. It also explicitly separates itself from edgegap_list_ping_beacons, so an agent can route correctly without opening a schema.

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

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

Gives concrete when-to-use conditions: pick geo_coordinates for edgegap_deploy when no player IPs are available, or report to a developer where players can be served from. It names the alternative tool (edgegap_list_ping_beacons) for the latency-beacon case, leaving nothing 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 and openWorldHint, yet the description adds a genuinely useful clarification that this tool does not perform pings, so agents will not expect latency data back. It does not cover pagination behavior, which is the remaining behavioral gap.

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

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

Three short clauses in one sentence plus a front-loaded scoping sentence; the core definition comes first and the read-only caveat last. Nothing is padded.

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

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

Safety is covered by annotations, return shape by the output schema, and the remaining ambiguity about what the tool actually does versus what the client does is resolved explicitly. Complete for a two-parameter list tool.

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

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

The description says nothing about the page or limit parameters. At 50% schema coverage, only 'limit' carries a schema note, so the description neither compensates nor worsens the gap; these are standard, self-explanatory pagination fields, which keeps this at the baseline.

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

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

States a specific verb and resource (list ping beacons) and then defines the resource itself: one host per region that a game client pings over UDP or TCP to measure latency. No sibling tool covers latency beacons, so the definition alone lets an agent place it correctly.

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

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

It establishes the usage context clearly: these measurements feed the matchmaker's latency rules and are taken before matchmaking. There are no explicit exclusions or named alternatives, but none of the sibling tools overlaps with this one, so the missing exclusion is low risk.

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 and openWorldHint, so the safety profile is covered; the description adds the non-obvious disclosure that a never-pushed image returns status "not_found" with no tags rather than an error, plus the downstream failure it prevents. It does not touch auth requirements, rate limits, or pagination behavior, so it stops short of a 5.

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

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

Four tight sentences with the purpose front-loaded, followed by the workflow reason, the edge-case return, and the scope limit. No filler or repetition of the title.

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

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

With an output schema present, return values need no explanation, and the description covers purpose, trigger, and the not_found edge case. Only minor gaps remain, chiefly the undescribed 'page' parameter and no note on how many tags a typical response yields.

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 67% and image_name already has a rich schema description (name only, no project/registry host/tag, project read from token), so the description mostly restates rather than extends it. The undocumented 'page' parameter is not addressed, and nothing is said about how limit/paging interact with large tag lists.

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 + scope: lists tags pushed for one image in this organization's Edgegap registry, and states what is returned (push time and size). It is clearly distinguishable from siblings edgegap_delete_registry_tag and edgegap_get_registry_credentials.

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

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

Explicitly states when to call it (after docker push, before edgegap_create_app_version) and why, and names the exclusion: images in Docker Hub, GHCR or other registries are not listed here. An agent knows both the trigger and the boundary without 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 and openWorldHint, but the description adds genuinely new behavioral context: relay sessions bill while open, so this listing has a cost-control purpose. It also discloses a coverage limit — authorization tokens are not listed — which an agent would otherwise wrongly assume.

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: the summary, the cost-driven motivation with the next action, and the limitation with the alternative. The most actionable information (what is returned) is 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?

Zero parameters, an output schema that covers the return shape, and annotations covering the safety profile mean the description only needs to supply motivation, follow-up, and limitations — all of which it does. Nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description uses that space to describe the listed fields instead, which the output schema already covers, so no credit above baseline.

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

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

States a specific verb and resource ("List this organization's active relay sessions") and even names the fields surfaced (id, status, readiness, player count), so what it returns is unambiguous. It is clearly distinguishable from the sibling edgegap_get_relay_session, which it explicitly routes single-session reads to.

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

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

Gives an explicit use case (find leftover sessions from earlier runs because sessions bill while open) and names the follow-up action with edgegap_delete_relay_session, plus the alternative edgegap_get_relay_session for reading one session. When-to-use, what-to-do-next, and the alternative are all 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 readOnly/idempotent/openWorld, but the description adds meaningful detail beyond them: it discloses that the GitHub version check 'reads one version number, no Edgegap API call', which clarifies the openWorld behavior and reassures the agent no Edgegap-side side effects occur. It stops short of describing ordering or result size, so not a full 5.

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

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

Three tight sentences, front-loaded with the purpose and followed by the routing guidance and the version-check note. Dense with useful detail, though the final parenthetical about GitHub is slightly tacked-on rather than integrated into the flow.

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

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

With no output schema, the description carries the return-value burden and does it: it explains that each entry states engine/netcode/backend, and that server instructions map projects to skills. Nothing an agent needs in order to decide to call it and interpret the result is missing, though the shape of the GitHub version-check result is only lightly described.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds no parameter information because none is needed, and the empty schema is fully consistent with the described behavior.

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

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

States a specific verb+resource ('List the Edgegap agent skills') and immediately defines what a skill is (tested step-by-step workflows with templates and pitfalls). It also explicitly contrasts itself with the sibling edgegap_get_skill, which loads a single skill, so an agent can choose between them without opening the schema.

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

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

Gives an explicit trigger ('Before working on a game project, load the matching skill with edgegap_get_skill') and names the fallback ('edgegap' covers any other engine and routes to the rest). It also flags the secondary purpose of reporting whether a newer skills pack exists on GitHub, so the agent knows both reasons to call 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 destructiveHint=false and non-idempotency, but the description adds real value beyond them: it clarifies that the report is a side-channel moderation signal to a studio's backend and that the deployment keeps running. It stops short of saying what the call returns or whether a report can be withdrawn, so it is strong but not complete.

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: purpose, non-effect, and usage routing, with the routing constraint front-loaded where the agent needs it. No repetition of schema content and 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 4-parameter write-adjacent tool with no output schema, the description covers purpose, side effects, and sibling routing, which is most of what an agent needs. It leaves the response shape and any rate limiting unstated, a modest gap given annotations already cover the safety profile.

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

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

Schema description coverage is 100%, so the schema already documents reason, metadata, request_id and dry_run fully. The description adds only framing ('short reason and optional key/value details') and says nothing about the dry_run escape hatch, so it neither compensates nor needs to. Baseline 3 applies.

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

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

States a specific verb and resource ('Report a problem with one deployment'), names the underlying API endpoint, and explicitly delimits it against what it is not ('does not stop the deployment'). An agent can distinguish it from edgegap_stop_deployment and edgegap_get_deployment_logs without opening any schema.

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

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

Gives an explicit when-to-use rule ('only when the developer asks to report a deployment') and names an alternative with its trigger condition ('for a crash, read edgegap_get_deployment_logs first'). Both the positive case and the exclusion are 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 declare destructiveHint=true and idempotentHint=true, so the safety profile is largely covered. The description adds real context beyond that: the blast radius is scoped to a single player and the session plus other players survive, which prevents an agent from overestimating the destruction implied by destructiveHint. It does not cover auth requirements or behavior on an already-revoked/expired token.

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, no filler. The action and scope come first, and the 'session and other players stay' clause is a compact, high-value carve-out rather than preamble.

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

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

For a 3-parameter mutation with annotations and no output schema, the description is nearly sufficient: it gives action, token provenance, and effect. Remaining gaps are minor — no statement about return value or failure modes such as an unknown/expired token.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema by identifying where user_authorization_token comes from (get_relay_session or authorize_relay_user) and reinforcing that it belongs to the player, not the session — useful provenance the schema does not supply.

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: 'Revoke one player's access to a relay session.' It makes the granularity explicit (one player, not the whole session), which separates it from edgegap_delete_relay_session and edgegap_authorize_relay_user in the sibling list.

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

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

Names the token source tools (edgegap_get_relay_session, edgegap_authorize_relay_user) and clarifies the effect: 'the session and the other players stay,' implicitly distinguishing this from tearing down a session. It stops short of stating explicit when-not conditions or edge cases (e.g. revoking the last player).

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

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

Annotations already declare destructiveHint, idempotentHint and openWorldHint, so safety is covered. The description adds real value beyond them: the SIGTERM graceful-shutdown semantics and the refusal of empty IDs, wildcards, and lists, which the annotations do not express.

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

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

Three sentences, front-loaded with the action and mechanism. The 'exactly one deployment' point is stated twice, a minor redundancy, but every sentence otherwise 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 destructive two-parameter tool with no output schema, the description covers mechanism, scope constraints, and workflow guidance. Return-value behavior is unspecified, but that is a minor gap given the annotations carry the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: request_id must be an exact, non-empty single ID and wildcards/lists are rejected. This sharpens usage beyond the schema's example value.

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 ('stop one deployment by request_id') and constrains scope to exactly one deployment. It is clearly distinguishable from siblings like get_deployment, list_deployments, and deploy, and even notes the SIGTERM mechanism.

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 actionable workflow context ('Stop every deployment you started for testing before ending your task') and explicitly rules out bulk stops. It doesn't name alternative tools, but the when-to-use guidance is clear enough to drive correct 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?

Adds substantial context beyond the annotations: tags are labels only and invisible to the game server, and the 'edgegap-mcp' tag is protected because cleanup depends on it. Also discloses the return value (current tags), which the annotations cannot.

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 sentences, front-loaded with the action and resource, followed by intent, then caveats, then return value. Nothing is redundant with the schema text.

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

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

No output schema exists, and the description explicitly states the return value (the tags now on the deployment). Combined with annotation coverage and full schema descriptions, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema documents request_id, add, remove and dry_run in detail. The description still contributes value by framing the deployment as 'one running deployment' and by flagging the protected tag that constrains valid values for the remove 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 specific verbs (add/remove) plus the exact resource (tags on one running deployment) and gives concrete intent examples (mark the match served, mark a test done). Clearly distinct from siblings like edgegap_get_deployment or edgegap_list_registry_tags.

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

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

Gives concrete usage contexts — labeling a match or test — and names the downstream consumer, edgegap_list_deployments, that makes tagging worthwhile. It lacks an explicit 'do not use this for X' exclusion, but the positive routing is clear enough for an agent to choose correctly.

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 idempotent, non-destructive, open-world, but they cannot express effect scope. The description supplies exactly that: turning off blocks new deployments of every version under the application while running deployments keep running, and nothing is deleted. That is the key behavioral fact an agent needs before flipping the flag.

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 core action, then the blast radius, then the use case. No filler and no repetition of the 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?

For a single-flag toggle with full schema coverage, annotations, and no output schema, this covers what an agent needs. The only omission is the dry_run verification path, which the schema already explains, so the gap is minor.

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

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

Schema description coverage is 100% and is_active is already documented as 'false blocks new deployments; true allows them again', which the description largely restates. The dry_run parameter is fully documented in the schema but unmentioned here, so the description adds little beyond structured fields. Baseline 3 applies.

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

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

States a specific action (set whether an application accepts new deployments) on a specific resource (application), not the version or deployment level. That scoping distinguishes it from edgegap_update_app_version and the deployment siblings without needing to name 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?

"Use it to pause an application without deleting anything" gives a clear use case and implicitly rules out deletion as the path to stopping deployments. It stops short of naming an explicit alternative or when-not-to-use case, but the context is unambiguous.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, reducing the burden. The description adds real behavioral context (partial-update merge semantics, running vs new deployments, refusals, secret values not readable), but the ports/env whole-list replacement is arguably a destruct-on-unpassed-value behavior that sits in tension with destructiveHint=false — the description discloses it, so it's guidance rather than a contradiction, though it warrants caution.

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

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

Front-loads the core purpose and keeps sentences dense with actionable detail. It is long and slightly sprawling, but nearly every clause carries operational value (replacement rules, refusals, coupling constraints), so 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 an 18-parameter mutation with no output schema, the description covers merge semantics, refusals, destructive list-replacement, secret-handling, and parameter coupling — everything an agent needs to call it safely without opening 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 coverage is 94% so the schema already documents most params. The description still adds cross-parameter meaning the schema cannot: cpu_units and memory_mb must change together, ports/env replace the entire list, and the registry-login placeholder must be omitted to preserve it. This genuinely supplements structured data.

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

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

States a specific verb+resource ('Change settings on an existing version') and immediately frames it against creating a new one. Enumerates the concrete editable settings (image tag, active flag, max_duration, registry login, force_cache, grace period) so an agent distinguishes it from edgegap_create_app_version and edgegap_get_app_version.

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

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

Explicitly says when to use it (change an existing version rather than create), names alternatives (edgegap_create_app_version for the same refusals, edgegap_get_app_version to read current ports/env, edgegap_deploy to override resources for one deployment). Covers when-not and points to sibling tools for adjacent needs.

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 discloses exactly what apply mutates (hand-copied skill files from bundled sources), which external commands may be run and under what gate, and that commands are merely listed when the env flag is off. It also states a negative safety fact: skill text is never downloaded by this tool.

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

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

Front-loaded with the verb and the apply/no-apply split, then details. The middle sentences are dense and clause-heavy (nested parenthetical about npx/claude commands), but every sentence carries operational information rather than filler.

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

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

No output schema exists, yet the description says what the check produces (comparison of each skill with latest on GitHub) and what the apply branch does in both gated and ungated states. For a 2-parameter, 0-required tool that is complete enough to call correctly.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description adds real meaning on top: apply=true implies file rewriting and updater execution rather than a passive refresh. The installed_versions semantics beyond the schema (hidden installs) are echoed from the schema but the interaction with the check is clarified.

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 (check/update installed Edgegap agent skills) and enumerates the install kinds it covers (skills CLI, Claude Code plugin, hand-copied folders). It also carves itself away from siblings: 'The skills served by edgegap_get_skill need no update here.'

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

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

Explicit when/when-not: 'Without apply it only checks and changes nothing,' 'With apply=true it rewrites...', 'Ask the developer before applying.' It also names the operator precondition (EDGEGAP_ENABLE_SKILLS_UPDATE=1) that changes what actually happens.

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=true, openWorldHint=false and idempotentHint=true, and the description reinforces this with 'Makes no API calls', so an agent knows it is a pure local check. Beyond that it enumerates the actual failure classes detected (ARM/Windows images, root Unreal, missing -batchmode -nographics, localhost binding, EXPOSE/port mismatch, protocol vs netcode mismatch, 'latest' tag, bad CPU/memory ratios), which is real behavioral context annotations cannot carry.