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

Annotations already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that a token is returned and that the operation augments an existing session, but says nothing about failure modes (e.g., unknown session_id) or any IP validation 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, front-loaded with the action and scope, followed by the return value. No filler or restatement 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 2-parameter mutation with no output schema, the description covers the return value (authorization token) and the operational context. Only error/edge-case behavior (invalid or expired session) is left unaddressed, which is a minor gap.

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

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

Schema description coverage is 50%: user_ip is documented ('Public IP of the joining player') but session_id has no schema description. The description's phrase 'existing relay session' and 'by public IP' loosely map to the two params but add no 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 (authorize), resource (player/relay session), and the exact scope: adding a player to an already-created session. This clearly differentiates it from edgegap_create_relay_session (initial creation) and edgegap_get/delete_relay_session.

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 precise usage condition: 'for a player joining after the session was created.' This implies the alternative is session creation, but it never names edgegap_create_relay_session explicitly, so the routing is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real value beyond them by disclosing the version/port verification check and the crucial caveat that no server-side matchmaker is created, making the 'generates a file, does not deploy' behavior unambiguous.

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 output is front-loaded in the first clause, followed by the key constraint and workflow. It is a fairly dense paragraph but each sentence (capability, verification, no-API caveat, recommended setup) carries distinct information.

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

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

For a 12-parameter tool with no output schema, the description covers the main concept and the return/config-file expectation. It stops short of explaining every optional parameter, but combined with 83% schema coverage an agent has enough to call it correctly.

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

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

Schema description coverage is 83%, so the schema already documents most parameters. The description echoes the schema's semantics (team count/size, latency rule, expansions that relax rules over time) without adding format or syntax detail the schema lacks, so the baseline 3 is appropriate.

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

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

Names a specific verb and resource ('Generate a ready-to-upload Edgegap matchmaker JSON configuration') and enumerates the scope of what one profile contains. An agent can immediately tell it apart from sibling tools like edgegap_create_app or edgegap_deploy, none of which build matchmaker configs.

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 clarifies that Edgegap has no API for creating a matchmaker and that this tool does NOT create one, instructing the agent to save the result and have the developer upload it manually. This is clear usage context, but it describes the output workflow rather than naming a sibling alternative to pick instead.

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

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

Annotations already declare destructiveHint=false and idempotentHint=false; the description adds that creating an application does not deploy anything, which is crucial behavioral context. It also implies a non-destructive nature but avoids repeating annotation-mandated details. This goes beyond annotations by clarifying the tool's limited scope.

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 only two sentences long, with the essential action front-loaded and the critical usage condition immediately following. Every word adds value, and the structure is efficient 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 that the tool has a simple schema with two simple parameters, full schema coverage, and no output schema, the description provides sufficient information for correct invocation. It lacks details on default behavior for is_active, but the schema covers that. The main gap is not specifying what the response looks like, but since there's no output schema, it's not mandatory. Overall, it's complete enough for its complexity.

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

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

Schema coverage is 100%, so both parameters are fully described in the schema. The description does not add extra parameter-level detail beyond what the schema provides, aligning with the baseline of 3. It doesn't repeat parameter names, but it also doesn't offer additional context like naming conventions beyond the schema's note.

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

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

The description clearly states the tool creates a new application to hold game server versions, distinguishing it from related operations like creating an app version. However, it doesn't explicitly mention that it's creating the top-level container versus other resource types, but the verb 'create' and resource 'application' are specific enough. It could more strongly differentiate from edgegap_create_app_version, but the follow-up note implicitly does so.

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

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

The description explicitly instructs to call this only after confirming no suitable application exists via edgegap_list_apps, and it tells the user to follow with edgegap_create_app_version. This provides clear when-to-use and sequential guidance, surpassing typical usage notes.

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

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

Annotations only supply openWorldHint/idempotentHint/destructiveHint; the description adds real behavioral context beyond them: the external-registry dependency, that verify_image makes a bad image fail here rather than at deploy time, and that reproducible tags prevent flaky deploys. It does not state permissions/error behavior, keeping it 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?

Five sentences, purpose front-loaded, then prerequisites, then resource-unit rules, then two actionable tips. No filler and every clause carries operational information.

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

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

For a 13-parameter mutation with no output schema and only safety-oriented annotations, the description covers the key unknowns: registry prerequisites, resource-unit math, verification, and tag hygiene. It omits version-name uniqueness expectations and any indication of the response payload, but the core call path is complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning absent from any single schema field: the 1024-units-per-vCPU conversion and the memory_mb >= 256 / <= 2x cpu_units constraint. Usage semantics for verify_image ('first version') also go beyond the schema text.

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

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

Specific verb+resource ('Register a container image as a deployable version of an application') that clearly separates it from sibling edgegap_create_app and edgegap_list_app_versions. An agent can tell exactly what object is being created and from what input.

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 preconditions (image must already be pushed to a registry Edgegap can pull from) and routes the agent to edgegap_get_registry_credentials and edgegap_list_registry_tags for verification. It advises setting verify_image on the first version and avoiding the 'latest' tag, but doesn't explicitly contrast with edgegap_create_app for the 'when not to use' case.

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

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

Annotations cover openWorld/idempotent/destructive, but the description adds substantial context beyond them: the host-risk profile (host can cheat, has a latency advantage, host's PC caps the match, match ends if host quits), that the call blocks until ready, what is returned (relay address plus per-player authorization tokens), and that sessions are billed while open with a cleanup path via edgegap_delete_relay_session.

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 warnings are front-loaded and every sentence carries real decision weight for a high-stakes, billable, non-default tool. It is long and slightly repetitive about the host's role and the 'no server image' caution, but not padded in a way that harms comprehension.

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 payload (relay address and per-player authorization tokens), the blocking behavior, billing implications, and the deletion follow-up. Nothing an agent needs to call and then manage this tool correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the host-first ordering of user_ips and points to edgegap_authorize_relay_user for late joiners, but these details already live in the schema, so it adds little beyond it.

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

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

The description states a specific verb and resource ('Creates an Edgegap relay session') and explicitly contrasts it with the sibling edgegap_deploy by declaring 'A relay is NOT a game server'. An agent can distinguish this tool from deployment tools without opening any schema.

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

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

It gives explicit when-to-use ('Only use this when the developer has chosen peer-to-peer/host-client, or the netcode is already a listen server'), when-not ('for a multiplayer match, deploy an authoritative dedicated server with edgegap_deploy instead'), a routing instruction to ask first if that hasn't been established, and an explicit anti-pattern ('Never pick it only because it needs no server image'). This is a complete routing guide.

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 the safety profile is structured. The description adds real value beyond that by disclosing the consequence: 'Connected players lose their relay connection.' It does not mention auth requirements 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?

Three short sentences, action front-loaded, with the impact statement and cleanup guidance following in priority order. 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 one-parameter destructive delete with annotations covering idempotency and destructiveness, the definition covers the operation, its side effect, and a cleanup workflow. The only real gap is the unexplained session_id, which is minor at this complexity.

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

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

Schema description coverage is 0% and the single parameter session_id is undocumented in the schema or description. The definition never says where session_id comes from (e.g., create_relay_session) or what format it takes, so it fails to compensate for the coverage gap.

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

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

States a specific verb and resource: 'Close one relay session.' An agent can distinguish it from the create/get/authorize relay siblings by name. It does not explicitly name alternatives, but the operation 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?

The description gives a lifecycle directive ('Delete every session you created for testing before ending your task'), which implies when cleanup is appropriate but does not compare against siblings or state prerequisites such as needing the session_id from create_relay_session.

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 non-idempotent, non-destructive, open-world behavior, so the description isn't carrying the safety burden, but it adds genuinely new async semantics: the call 'returns immediately with a request_id' and the server 'has no connection details yet'. That tells the agent not to expect a usable address in the response, which the annotations do not convey.

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

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

Four sentences, front-loaded with the core action and its async consequence, with no filler. The final cleanup sentence is usage guidance rather than capability description, but it is short and operationally useful rather than padding.

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

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

For a 7-param deployment tool with no output schema, the description covers the key unknowns: what it starts, what it returns immediately (request_id), and how to obtain the connection address. It leaves out failure modes, quota/pricing limits, and whether the deployment auto-expires, which would round out the picture.

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

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

Schema description coverage is 100% and the nested users object is fully documented, so the baseline is 3. The description only restates schema content ('placed near the players you specify') and adds no format, cardinality, or override guidance for cpu_units/memory_mb/env/tags.

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 distinguishes the resource from siblings like edgegap_create_app_version or edgegap_create_relay_session. The scope ('one', 'authoritative', 'near the players') is precise enough that an agent can pick it out without opening the schema.

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

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

Explicitly frames this as 'the recommended way to host a multiplayer match' and names the required follow-up tool (edgegap_wait_for_deployment) plus a cleanup obligation ('Always stop deployments you started for testing'). It never states when to prefer this over edgegap_create_relay_session, so it stops short of a full when/when-not contrast.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, and the description reinforces this with 'Makes no API calls' – explaining why a 'write' tool is read-only (it emits a local file). It also discloses the validation step against edgegap_validate_server_config and the assumption-reporting behavior. Minor gap: it doesn't say what happens if required build info is missing beyond 'listed under assumptions', nor what the returned text looks like.

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

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

One dense paragraph that front-loads the action and the output contents before moving to preconditions and follow-ups. Every clause carries information, though the mid-sentence list of engine flags and file-system details makes it slightly run-on compared with a tighter two- or three-sentence split.

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

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

No output schema exists, but the description explains what the generated artifact contains, where it is written, that it is checked against edgegap_validate_server_config before return, and that assumptions must be confirmed. For a generator tool with only one required parameter, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter behavior the schema cannot express: omitted values become assumptions that must be confirmed, and the engine choice drives defaults for build path, executable and headless flags. It does not re-explain the port/netcode lists, which the schema already covers.

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 this project's headless game server build, ready for Edgegap') and enumerates the exact contents it produces (base image, build folder, binary permissions, headless flags, non-root user, CRLF fixes, EXPOSE). This is clearly distinguishable from siblings like edgegap_create_app_version or edgegap_validate_server_config.

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 trigger ('Call this when the project has no Dockerfile, before building anything'), explicit precondition ('Look at the build output first so you can pass the real build folder, binary name and port'), and an explicit follow-up path (write to Dockerfile, then build). Usage is fully determined.

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

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

Annotations already establish readOnlyHint=true, so the read-only behavior is covered. The description adds value by disclosing that connection address and ports appear only once the deployment is ready, which helps the agent understand timing and response behavior.

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

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

Two short sentences with no filler: the first states what the tool does and what it returns, and the second routes to the preferred sibling when relevant. The most important 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?

For a simple single-parameter read tool with readOnlyHint and full schema coverage, the description is sufficient. An agent knows what to call, how to get the request_id, what to expect in the response, and when to use wait_for_deployment instead.

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

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

The input schema already documents request_id fully, including that it is returned by edgegap_deploy, so schema coverage is 100%. The description reinforces this but does not add meaningful semantics beyond the schema, warranting the baseline score.

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: 'Read the current status of one deployment' and adds the relevant output ('connection address and ports once it is ready'). The singular 'one deployment' clearly distinguishes it from list-style 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 explicitly names the alternative edgegap_wait_for_deployment and gives the condition for preferring it: a deployment you just created, because that tool polls for you instead of requiring a loop. This is clear, actionable usage guidance.

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

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

With readOnlyHint and openWorldHint already present, the description adds useful non-obvious behavior: logs include crash output and are retained for stopped deployments only if Endpoint Storage was configured. No contradiction with annotations.

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

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

Three tight sentences cover what the tool returns, when to call it, and an important retention caveat. No filler; the usage guidance is front-loaded before the edge case.

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

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

For a simple read-only log retrieval tool with two well-documented parameters and annotations covering safety, the description provides enough context: what logs are retrieved, when to use it, and the retention limitation. The lack of an output schema is not a gap here.

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 clear descriptions of request_id and max_characters. The description does not add parameter-level details, but the baseline 3 is appropriate because the schema already carries the semantic load.

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 ('Retrieve') and resource ('stdout/stderr and crash output for a deployment'), making the tool's function unambiguous. This is clearly distinct from sibling tools that list, stop, or create deployments/apps.

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

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

It gives explicit trigger conditions: call when a deployment errors or a server exits unexpectedly, and explains the diagnostic value of the crash exit code. It does not explicitly name alternatives or when-not-to-use cases, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, and the description explains exactly why it is not read-only ('Provisions the registry project on first use'). It adds high-value context beyond annotations: token scope (registry-scoped, not org API token) and a security constraint (pass via --password-stdin, never as an argument, never write to files). No contradiction with the structured hints.

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

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

Front-loaded with the return payload, then when-to-use, then provisioning side effect, then token safety, then prerequisite call. Every sentence carries distinct operational information and none is redundant.

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

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

No output schema exists, but the description enumerates the return payload (URL, project, username, token, commands) and covers the mutation side effect, token scope, and sequencing. An agent has everything needed to call it safely and correctly.

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

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

Schema description coverage is 100%, so both parameters (tag, image_name) are already documented, including the 'Never latest' rule. The description only alludes to them via 'the exact docker login, build and push commands for your image,' adding essentially no meaning beyond the schema. 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?

Names a specific verb and resource (return registry URL/project/username/token plus exact docker commands) and pins it to a concrete artifact (registry.edgegap.com). Clearly distinguishable from sibling edgegap_list_registry_tags, which lists tags rather than handing back credentials and commands.

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 trigger: 'Use this when the server image is not in a registry yet — no Docker Hub account needed.' It also sequences a sibling dependency ('Call edgegap_validate_server_config before building'), so the agent knows both when to invoke this and what to do first.

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

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

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 and openWorldHint=true, covering the safety profile. The description adds useful context about organizational scope and the meaning of an application, but does not disclose pagination behavior or response details.

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-load the action, then give a concrete usage rule, then define the domain concept. 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?

The description is sufficient for deciding to call it and knowing its scope, and the annotations cover safety. It falls slightly short by not hinting that results are paginated or that page/limit should be considered for a complete inventory.

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 two pagination parameters are optional, and only 'limit' carries a schema description; 'page' has only type/constraints. The description adds no parameter-level detail, so it fails to compensate for the incomplete 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?

Opens with a specific verb and resource: 'List the applications in the Edgegap organization.' The definition of an application as grouping versions of one game server distinguishes it from sibling list_app_versions and places it clearly in the create/deploy workflow.

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

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

Explicitly instructs the agent to call this before creating or deploying anything to avoid duplicate applications. It does not name sibling alternatives or state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, covering the read-only safety profile. The description adds useful context about the output content, but does not disclose any edge behaviors such as pagination, ordering, or error conditions when an application does not exist.

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 tightly written sentences with no filler. The first states the core action and output scope; the second gives practical use cases. Every sentence earns its place.

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

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

For a simple read-only tool with one well-documented parameter and no output schema, the description covers what the tool returns and why an agent would call it. It could mention absence of an application as a possible failure, but this is a minor gap.

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

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

Schema description coverage is 100%, so the single 'application' parameter is already documented in the schema. The description does not add format or syntax detail beyond that, which is acceptable given the schema's completeness.

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'), a precise resource ('versions under an application'), and the key contents of the result ('container image and resource settings'). It is clearly distinguished from sibling edgegap_list_apps, which lists applications rather than versions.

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?

Provides explicit use cases: 'find the version name to deploy' or 'copy settings from a working version when creating a new one.' It does not name alternatives or state when not to use it, but the intended context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the cost consequence of orphaned deployments, the constraint that at most one filter per field is allowed, and per-field operator support that the schema does not encode.

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

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

The purpose is front-loaded, but the body is a dense single-paragraph run-on mixing use case, field enumeration (already in the schema enum), example filter syntax, and operator rules. Bullet-style structuring of the operator matrix would make it far easier to parse.

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 never characterizes what a returned deployment looks like or its key fields, which matters for a list tool. Input semantics are thoroughly covered and annotations carry the safety profile, but the return shape is an unaddressed gap.

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

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

Schema description coverage is 100%, so much of the filter syntax is already documented. However, the description adds constraint meaning the schema lacks: which operators apply to which fields (eq/neq everywhere but created_at; in/nin only on specific fields; ilike only on fleet_name/host_name) and the one-filter-per-field rule.

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 scope of optional filtering and sorting. It is clearly distinguishable from edgegap_get_deployment (single) and edgegap_wait_for_deployment (blocking) 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 use case with a rationale: find deployments left running from earlier sessions before starting new ones, because orphaned servers cost money. It does not name a competing sibling tool to route against (e.g. get_deployment for a single deployment), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by explaining the downstream failure mode this check guards against and what the response contains. It omits pagination behavior, 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?

Two sentences, zero filler, with the purpose and the return contents front-loaded before the workflow hint. 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?

No output schema exists, and the description does adequately describe the payload (tags with push time and size) along with the workflow context. The only real omission is how paging works for retrieving beyond the default limit.

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 67%; image_name has a useful schema description and limit documents its default, but page is undocumented in both schema and description. The description adds no parameter-level detail (format, paging), so it neither compensates for the gap nor regresses below 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 (list) and resource (tags pushed for one image) scoped to the organization's Edgegap registry, and names the concrete return fields (push time, size). This clearly distinguishes it from the app/deployment 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 when to call it ('after docker push to confirm the tag landed') and what it prevents ('edgegap_create_app_version, which otherwise fails later with an image-pull error'), naming the sibling tool directly.

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 the tool destructive and idempotent; the description adds the behavioral detail that stopping is graceful and sends SIGTERM to the container. It also scopes behavior to exactly one deployment. This adds context beyond the structured hints without contradicting 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 short sentences, each earning its place: the first defines the operation and mechanism, the second gives a task-level cleanup directive, and the third sets scope. Information is front-loaded and there is no filler.

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

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

For a single-parameter, annotation-rich tool with no output schema, the description covers what the agent needs: the operation, the mechanism, the required identifier, and the cleanup expectation. Nothing material is missing.

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

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

Schema coverage is 100% and the request_id parameter is already described as 'The request_id of the deployment to stop.' The description adds little beyond confirming lookup by request_id and single-deployment scope, so it earns the baseline score for schema-covered parameters.

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

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

States a specific action ('stop'), a specific resource ('one deployment'), and the required identifier ('by request_id'), and distinguishes itself from any bulk-stop alternative ('bulk stop is deliberately not exposed'). It is unambiguous and differentiates from sibling tools like edgegap_deploy.

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?

Provides explicit usage context: the agent should stop every deployment it started for testing before ending its task. It also clarifies the tool's single-deployment scope and that bulk stop is intentionally unavailable, preventing the agent from seeking a bulk alternative. It does not explicitly point to sibling tools for finding request_ids, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is known. The description still adds real value beyond them: it enumerates the concrete failure classes detected (ARM/Windows images, root Unreal, missing -batchmode -nographics, localhost binding, EXPOSE/version port mismatch, protocol/netcode mismatch, 'latest' tag, bad CPU/memory ratios) and states 'Makes no API calls,' which confirms it is a local static check. It stops short of describing the returned report.

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

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

The purpose and timing are front-loaded in the first sentence, followed by a dense but well-ordered list of concrete failure modes rather than vague hedging. It is long, but nearly every clause names a distinct, actionable check, 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 a 9-parameter, no-output-schema validation tool, the description conveys purpose, timing, alternative routing, and the failure classes it catches. The main gap is the shape of the result (pass/fail report, list of issues) and how the optional params like docker_image/docker_repository feed the check.

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 44%, so several parameters (cpu_units, memory_mb, docker_tag, docker_image, docker_repository) carry no explanation anywhere. The description partially compensates by telling the agent to pass the Dockerfile text (read from disk first) and by conveying the port/netcode relationship that drives validation, but it adds little for the remaining unlabeled params. Baseline 3 is appropriate given the partial 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 (validate/check) and resource (game server Dockerfile plus ports/resources) scoped against Edgegap's requirements. It explicitly distinguishes itself from edgegap_generate_dockerfile and from the build/push/version/deploy flow, so an agent knows exactly what this tool does and does not do.

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 timing ('BEFORE building and pushing') and a clear branch condition with an alternative ('If there is no Dockerfile yet, call edgegap_generate_dockerfile instead'). This is exactly the when-to-use / when-not-to-use / alternative structure.

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 idempotentHint, so the safety profile is covered. The description adds valuable behavioral details: polling behavior, backoff, timeout handling, and that it reports container error detail on failure. This is more than the annotations provide, though it doesn't specify exact timeout semantics beyond the parameter.

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 with zero waste. The purpose is front-loaded, and the usage guidance is compact and direct. Every clause serves a purpose, making it easy for an agent to parse quickly.

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

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

For a polling tool with no output schema, the description covers the full lifecycle: what triggers it, what it does while polling, what it returns on success, and what happens on failure (error detail). An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% with both parameters documented. The description adds the key contextual meaning that request_id comes from edgegap_deploy, which is not in the schema. This extra clarification goes beyond the schema's field descriptions, justifying a score above the baseline 3.

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

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

The description states a precise verb ('poll') and resource ('deployment'), and the outcome ('return the connection details'). It explicitly positions itself relative to edgegap_deploy and mentions that it handles backoff, which distinguishes it from a generic status check like edgegap_get_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?

It clearly says 'This is the tool to call right after edgegap_deploy' and instructs 'Do not build your own polling loop', giving an explicit when-to-use and a when-not-to alternative. This leaves no ambiguity about the intended context.

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