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?

Annotations already signal read-only/idempotent, which is consistent with a generator. The description adds real behavioral detail beyond annotations: it performs a lookup that verifies the referenced application version exists and has ports, and it explicitly clarifies that no server-side object is created and the developer must upload the config manually. It does not cover the inspect/verify_version toggles or failure modes when verification fails.

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 concrete artifact and its contents, then the critical caveat about manual upload. Four sentences all carry weight, though the closing sentence about authoritative dedicated servers is more recommendation than instruction and could be trimmed.

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

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

For a 13-parameter generator with no output schema, the description explains what is produced, what is verified, and what to do with the result. It does not describe the shape of the returned JSON beyond 'config', but the schema and the tool's generative nature make that a minor gap.

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

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

Schema coverage is already 85%, so the baseline is 3, but the description adds conceptual meaning the schema lacks: expansions are described as time-based rule relaxations ('relax the rules the longer a player waits'), and the latency rule is tied to the profiles's matching behavior. The two undocumented team-size parameters are only generically covered as 'team size'.

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, plus the exact contents (team count/size, optional latency rule, optional expansions). No sibling tool produces matchmaker configs, and the description makes that boundary obvious.

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

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

Gives a clear when-to-use context and an explicit when-not: 'Edgegap has no API for creating a matchmaker, so this tool does NOT create one.' It also prescribes the follow-up workflow (save to file, upload manually on the dashboard). It stops short of pointing to any alternative or prerequisite sibling tools (e.g. app-version lookup tools), so not a full 5.

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

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

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?

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, 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?

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 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?

Far exceeds the annotations (which only say non-read-only, idempotent, non-destructive). It discloses the token-scope behavior (quick-start vs regular API token), the fallback response when credentials are unavailable, and handling constraints (registry-scoped token, use --password-stdin, never a CLI argument, never written to 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 the purpose and the registry URL, then ordered by decision flow (when to use → auth caveat → token handling → prerequisite). It is long at roughly 110 words, but nearly every sentence encodes a security or routing constraint that cannot be dropped.

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 auth behavior, fallback path, token hygiene, and a prerequisite tool, which is substantial for a credential tool with no output schema. It does not state what happens if the optional 'tag' or 'image_name' are omitted, a minor gap given the 0 required parameters.

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

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

Schema description coverage is 100%, so the schema already documents both 'tag' (never "latest") and 'image_name' (pattern, no project/tag). The description only adds that the returned commands are built 'for your image', which is implied. Baseline 3 applies when the schema carries parameter meaning.

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: fetching push login credentials for the organization's private Edgegap container registry, plus the exact docker login/build/push commands. It is clearly distinguishable from the sibling edgegap_list_registry_tags, which only lists tags rather than supplying 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 says when to use it ('when the server image is not in a registry yet'), when it will not work ('with a regular API token this tool cannot fetch them... do not retry'), what to do instead (copy from the dashboard, ask the developer), and names a prerequisite sibling ('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 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 and openWorldHint=true, so safety is covered. The description goes further by disclosing the returned content, including the non-obvious detail that ports carry a TLS Upgrade flag needed by browser/WebGL clients for wss://, plus whether registry credentials exist for image pulls. It omits pagination/ordering behavior, which keeps 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?

Front-loaded with the verb and the returned fields, then the usage sentence. Every clause carries information; the descriptions of returned fields are dense but each one (TLS Upgrade, registry login) is actionable and not padded.

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

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

There is no output schema, so the description correctly carries the burden of describing return values and does so thoroughly. Remaining gaps are minor for a scoped list-under-a-parent call: no mention of ordering or pagination limits, and no explicit note that a nonexistent application errors.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains 'application' and even cross-references edgegap_list_apps as the source. The description adds no syntax, naming, or format constraints beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource ('List the versions under an application') and immediately enumerates the payload the agent will get back (container image, resources, ports/TLS, registry login). This is clearly distinguishable from edgegap_list_apps and edgegap_list_registry_tags, which operate on different resources.

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

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

Explicitly names three concrete use cases: finding the version name to deploy, verifying a version is ready before deploying, and copying settings when creating a new one. The last two also route implicitly to edgegap_deploy and edgegap_create_app_version, so the agent knows when this tool is the right first step.

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 constraints beyond that: at most one filter per field, operator availability varies by field, and only_agent_deployments cannot be combined with a tags filter. It does not describe the return shape or result volume, which is a minor gap for a tool with no output schema.

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

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

Purpose and the motivating use case are front-loaded, followed by the filter grammar. It is long, but the length is driven by genuinely dense query semantics rather than filler, and it includes worked examples. Slightly heavy for a single description but each clause carries information.

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

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

For a read-only, annotated list tool whose schema already defines limit and filter structure, the description supplies enough to call it correctly, including caveats and examples. The remaining gap is that it never characterizes the returned deployment objects, which matters somewhat given there is no output 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 100%, setting the baseline at 3, but the description meaningfully exceeds it: it maps which operators are valid per field (eq/neq everywhere except created_at, which uses eq/gte/lte; in/nin on specific fields; ilike with % wildcards only on fleet_name and host_name) and documents the only_agent_deployments equivalence to a tags filter. That per-field operator grammar is not inferable from the schema's flat operator enum.

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+scope ("List active deployments, optionally filtered and sorted"), which cleanly distinguishes it from the singular edgegap_get_deployment and from edgegap_deploy/edgegap_stop_deployment. An agent can identify the operation without opening the schema.

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

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

Gives a concrete when-to-use scenario with a rationale: find deployments left running from earlier sessions before starting new ones because orphaned servers cost money. It also routes a special case (only_agent_deployments for agent-started servers). It stops short of naming explicit alternatives for single-deployment lookups (get_deployment) or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond them: what the response contains (push time, size) and the operational consequence of skipping the check. It does not mention pagination behavior, 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 tightly packed sentences, zero filler. The scoping statement comes first and the workflow guidance second, which is the correct front-loading for a read-only lookup tool.

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

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

For a read-only list tool with annotations covering safety and no output schema, the description covers purpose, workflow placement, and return content. The only omission is how page/limit pagination behaves when many tags exist, which matters for a listing 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 67% and the schema itself already documents image_name thoroughly (excluding project, registry host, tag) and limit's default. The description adds no parameter-level syntax or constraints, 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?

States a specific verb and resource ('List the tags pushed for one image in this organization's Edgegap container registry') plus the returned fields (push time, size). It is clearly distinguishable from siblings like edgegap_list_apps and edgegap_list_app_versions, which target different resources.

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

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

Gives explicit when-to-use ('Call it after docker push to confirm the tag landed') and names the alternative/downstream tool (edgegap_create_app_version), including the concrete failure mode ('image-pull error') that this check prevents. Nothing is left to inference.

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

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

Annotations already declare 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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds genuinely new behavior: it is a purely local check ('Makes no API calls'), and it discloses the concrete validation rules applied (linux/amd64 only, root detection, Unity batchmode flags, localhost binding, EXPOSE/version-port mismatch, protocol/netcode mismatch, 'latest' tag, CPU/memory ratios). It stops short of saying how findings are reported.

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

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

Front-loaded with the purpose sentence, then a dense but non-redundant list of failure categories, closing with the sibling alternative and the no-API-calls note. The failure list is long but every item is a distinct, actionable check 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?

Covers the two things an agent most needs: what gets checked and that this is a safe local operation with an alternative when the Dockerfile is absent. The one real gap is the return contract — with no output schema and no statement of what a failed validation yields (findings list vs boolean), the agent cannot anticipate the response shape.

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

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

With only 44% schema coverage, the description compensates by binding several bare params to meaning: dockerfile ('Pass the Dockerfile text, read it from disk first'), netcode (protocol-vs-transport matching), docker_tag ('latest' rejection), cpu_units/memory_mb (ratios), and ports (must agree with version ports). It does not meaningfully clarify docker_image vs docker_repository, the engine auto-detection, or the port name/tls_upgrade fields.

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

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

States a specific verb and resource (validate a game server Dockerfile plus ports/resources) and pins the timing ('BEFORE building and pushing'), which cleanly separates it from edgegap_create_app_version, edgegap_deploy and edgegap_build_matchmaker_config. The enumerated failure classes make the scope unmistakable.

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 (pre-build/push, read the Dockerfile from disk first) and names the alternative for the opposite condition: 'If there is no Dockerfile yet, call edgegap_generate_dockerfile instead.' That is a textbook when/when-not/alternative split.

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.