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?

Beyond the annotations, the description adds valuable behavioral context: verify_image makes a bad image fail at registration rather than deployment, and resource units/memory constraints define server sizing. It does not contradict the openWorldHint/idempotentHint/destructiveHint annotations, and while it does not discuss auth or rollback, the annotations already cover the safety profile.

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

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

Four tight sentences with no filler; the core purpose is front-loaded in the first sentence, followed by constraints and recommendations. Every sentence adds either a precondition, a conversion rule, or a best practice, so the description is appropriately sized.

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 tool with no output schema, the description covers the non-obvious prerequisites, resource constraints, verification behavior, and tag strategy, while the schema handles parameter details. It does not describe response shape or failure modes, but this is not necessary for invoking the tool successfully, so the definition is nearly 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, and the description adds extra meaning: the registry-pull precondition, the 1024 cpu units = 1 vCPU conversion, and the advice to set verify_image on the first version. These details make parameter choices more actionable even though some duplicate 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?

The description opens with a specific verb and resource: “Register a container image as a deployable version of an application,” which clearly distinguishes this from sibling tools like edgegap_create_app or edgegap_deploy. The title and description align and scope the operation to version registration rather than app creation or 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?

The description provides clear context: use it to register an already-pushed image and states a precondition (“The image must already be pushed to a registry that Edgegap can pull from”). It offers operation-specific recommendations (verify_image on first version, avoid latest tag) but does not explicitly name alternatives or when-not-to-use conditions, 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?

It discloses an important behavioral trait not available in the annotations: the deployment is asynchronous and the returned request_id is not yet a usable address. It also surfaces the need to clean up test deployments, which is valuable guidance beyond openWorldHint/idempotentHint.

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

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

Compact and efficient: three sentences deliver purpose, async behavior, follow-up call, and cleanup guidance. Each sentence earns its place, and the most important workflow step is clearly 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?

Given that all seven parameters are fully documented in the schema and there is no output schema, the description properly provides the missing context: return value (request_id), asynchronous behavior, the next step (wait_for_deployment), and the need to stop test deployments. Nothing essential 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 the input schema already explains every parameter. The description slightly reinforces 'application version' and 'players you specify' but does not add substantial new meaning about the parameters or how they interact.

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

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

The description opens with a specific action, 'start one containerized instance of an application version', and clarifies geo-placement ('placed near the players you specify'). It is clearly a deployment creation tool and is easily distinguished from sibling tools like edgegap_wait_for_deployment, edgegap_list_deployments, and edgegap_stop_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 explicitly tells the agent to follow this call with edgegap_wait_for_deployment for connection details, and explains the timing caveat: it returns immediately, the server is still starting, no connection details yet. It also warns to always stop test deployments, which is concrete operational 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 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 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 meaningful behavior: it lists only 'active' deployments (not stopped ones) and supports optional filtering. The cost warning adds context about why listing is useful. This goes beyond the annotations 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?

Two sentences with zero redundancy. The core action ('List active deployments') is front-loaded, followed by the optional filter and a practical usage rationale. Every word earns its place; it's both concise and informative.

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 no output schema and high parameter coverage, the description is nearly complete. It covers purpose, usage, and the active-deployment scope. It doesn't mention pagination or response format, but those are typically inferred for list operations and the annotations already signal safety. Overall, 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 100% – both limit and filter have descriptions in the schema. The description's 'optionally filtered' mirrors the filter param but adds no new syntax or details. Since the schema already documents both parameters fully, the description provides no extra parameter-level value, meeting the baseline for high 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 ('List') and resource ('active deployments') with an explicit filter option. It clearly distinguishes from sibling tools like edgegap_get_deployment (single) and edgegap_stop_deployment (mutation), and even gives a concrete use case that sets it apart. An agent can immediately grasp what this tool does and how it relates to others.

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 a clear when-to-use context: 'find deployments left running from earlier sessions before starting new ones' with the cost warning. While it doesn't explicitly contrast with siblings or state exclusions, the guidance is actionable and context-rich, making it easy for an agent to decide when to invoke this tool. Slight gap: no mention of alternatives for single-deployment lookup.

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