Server Quality Checklist

Tool Scores

• service_setB
  3.1/5.0
  Behavior2/5

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

  The description says 'change' which correctly aligns with readOnlyHint=false and does not contradict the idempotentHint=true annotation. However, it adds little beyond the annotations: it does not disclose side effects (e.g., whether a redeploy is triggered), the optimistic-concurrency revision check implied by the 'force' parameter, or what happens to unset fields. For a mutation tool, this is a notable gap.

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

  Conciseness4/5

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

  The description is a single, well-structured sentence that front-loads the usage trigger and key examples. It earns a 4 for efficiency, but not a 5 because the trailing 'etc.' is a weak way to imply the full parameter set and the sentence could be slightly more explicit without adding length.

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

  Completeness2/5

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

  Given the complexity (13 parameters, no output schema, and a low schema coverage), the description is far too sparse to be complete. It leaves out crucial operational context: required parameters, effect of the optimistic-concurrency check, valid values for sourceType, and whether changes trigger deployments. An agent would need to inspect the schema deeply or guess, which is inadequate for a setter tool.

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

  Parameters2/5

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

  Schema description coverage is only 8% (only 'force' has a description), so the description must compensate. It names four parameters (source repo, branch, build command, start command) but silently omits the remaining nine (sourceType, containerPort, rootDirectory, watchPatterns, dockerfilePath, preDeployCommand, etc.) and does not explain required 'project' and 'service' parameters. This leaves significant parameter semantics undocumented.

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

  Purpose4/5

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

  The description gives a specific verb ('change'), a resource ('Lizard service's build/deploy configuration'), and concrete example fields ('source repo, branch, build command, start command'), which clearly distinguishes it from sibling tools like service_scale or service_delete. It loses one point because 'etc.' is vague and the description does not explicitly name the required project/service scope, leaving some ambiguity about what the tool targets.

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

  Usage Guidelines4/5

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

  The description clearly states when to use the tool: 'when the user wants to change a Lizard service's build/deploy configuration.' This provides a solid trigger condition. However, it does not explicitly mention alternatives like service_set_port or service_scale, nor does it state when not to use it, so it is strong but not fully comprehensive.

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

• service_renameB
  3.3/5.0
  Behavior2/5

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

  The annotations already indicate that this is a mutating, non-destructive, idempotent operation. The description adds no behavioral context beyond restating the purpose—there is no mention of validation behavior, effects on references, naming constraints, or consequences of renaming a service. With the full burden shifted to annotations, this is a minimal disclosure.

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

  Conciseness5/5

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

  The description is a single, directly relevant sentence with no filler. It front-loads the intended use and contains only information relevant to tool selection.

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

  Completeness3/5

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

  For a simple rename operation, the description covers the core use case: the user wants to rename an existing service. However, it leaves important operational details uncovered—parameter value semantics, whether the new name has constraints, and what happens on failure. The lack of an output schema and sparse parameter descriptions make this only minimally viable.

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

  Parameters2/5

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

  Schema description coverage is only 33%, and the description does not compensate. Only 'name' is documented in the schema, while 'project' and 'service' lack descriptions and are not explained in the description. The agent is left to infer whether these are IDs, names, or slugs, and no format or relationship guidance is provided.

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

  Purpose4/5

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

  The description states a specific verb and resource: 'rename an existing Lizard service'. This clearly distinguishes the action from create/delete/list operations. However, it does not explicitly differentiate itself from sibling tools like service_set or service_set_port, so it stops short of a 5.

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

  Usage Guidelines4/5

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

  The phrase 'Use this when the user wants to rename an existing Lizard service' gives a clear, explicit trigger condition for invoking the tool. It does not mention alternatives or exclusions (e.g., saying 'for port changes use service_set_port'), so it lacks the when-not guidance needed for a 5.

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

• domain_verifyA
  3.5/5.0
  Behavior2/5

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

  The description only says 'verify', which implies a check but doesn't disclose what the tool actually does beyond that—whether it queries DNS, updates status, returns a report, or has side effects. The annotations already declare idempotent and non-destructive traits, so the description adds little behavioral context, and the readOnlyHint=false annotation is left unexplained.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that immediately states when to use the tool and what it verifies. There is no wasted wording or redundant restatement of the title.

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

  Completeness2/5

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

  With no output schema, the description should explain what a successful verification looks like and any relevant behavioral nuances (e.g., DNS propagation delays, failure modes, prerequisites like a prior domain_attach). The current description only gives a high-level action, leaving the agent without enough information to correctly interpret results or handle edge cases.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It only clarifies that hostname refers to a custom domain attached to a Lizard service, but it does not explain the distinct meanings of project and service, value formats, or how the parameters relate to the action. This is insufficient for a three-parameter tool with no schema descriptions.

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

  Purpose5/5

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

  The description states a specific verb ('verify') and a clear resource ('DNS configuration for a custom domain attached to a Lizard service'). It distinguishes this tool from siblings like domain_attach and domain_delete by positioning it as the verification step, so an agent can tell what it does 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.

  Usage Guidelines4/5

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

  The description explicitly begins with 'Use this when...' and gives a clear trigger condition: the user wants to verify DNS configuration. It doesn't name alternatives or exclusions, but there are no sibling tools that perform DNS verification, so the context is adequate.

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

• secrets_refsA
  3.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuinely valuable behavioral context beyond those: it discloses that the tool returns reference templates (not actual secret values) that are meant to be injected into another service's secrets — preventing the wrong expectation of seeing raw secret data. 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.

  Conciseness5/5

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

  A single sentence of roughly 25 words that front-loads the usage trigger, states the resource, includes a concrete example, and contains zero filler. Every clause earns its place.

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

  Completeness3/5

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

  For a simple read-only listing tool, the core purpose is well covered and annotations carry the safety profile. However, there is no output schema yet no mention of return format, the parameters remain undocumented, and the distinction from secrets_list is only implicit — leaving gaps that could cause an agent to invoke it incorrectly.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate, but it only vaguely hints at the 'service' parameter through the phrase 'inject into another service's secrets.' The required 'project' parameter is entirely unexplained in both schema and description, and the optionality/relationship of 'service' is not clarified. This is a significant gap given zero schema help.

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

  Purpose4/5

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

  The description names a specific action — 'see the available reference-variable templates' — with a clarifying example ('like postgres connection strings') and the injection use case. It is distinguishable from the confusable sibling secrets_list (which would show actual secrets) by the 'templates... inject into another service's secrets' framing, though it does not name that sibling explicitly.

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

  Usage Guidelines3/5

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

  The description opens with 'Use this when the user wants to see...' which gives a clear trigger condition for invocation. However, it provides no exclusions and no explicit routing to the highly confusable alternatives in the sibling list (secrets_list, secrets_set, secrets_delete), so an agent has no guidance on when to choose this tool over them.

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

• project_listA
  3.8/5.0
  Behavior3/5

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

  Annotations already carry the safety profile: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds only the scoping detail that this shows the user's own projects and supports an optional workspace filter. No return/pagination/auth details are given, but the annotation coverage lowers the burden.

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

  Conciseness5/5

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

  The description is a single concise, front-loaded sentence with no filler. Every phrase contributes: the use case and the optional filter are both conveyed efficiently.

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

  Completeness4/5

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

  This is a simple read-only list operation with one optional parameter, rich annotations, and no nested objects or output schema. The description adequately covers when to use it and what filtering is possible. A mention of return shape could help slightly, but for this complexity it is not a meaningful gap.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the workspaceId parameter is already documented as filtering to that workspace ID. The description's mention of 'optionally filtered to one workspace' reinforces the idea but adds no new meaning beyond the schema.

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

  Purpose4/5

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

  The description clearly identifies the action ('see' list) and resource ('Lizard projects'), and it adds the optional workspace filtering scope. It does not explicitly contrast with sibling tools like project_create or workspace_list, so it falls short of a 5, but the core purpose is unambiguous.

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

  Usage Guidelines4/5

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

  The description starts with 'Use this when the user wants to see their Lizard projects', which directly states the intended triggering condition. It does not provide explicit exclusions or name alternative tools, but the context is clear enough for an agent to select it appropriately.

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

• service_scaleA
  3.8/5.0
  Behavior3/5

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

  The annotations already convey mutation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds no behavioral details beyond the verb, such as whether scaling causes restarts. This is acceptable but not rich; no contradictions exist.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. Every word supports tool selection and invocation.

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

  Completeness4/5

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

  Together with the input schema, which documents units, allowed values, 'apps only'/'addons only' constraints, and grow-only storage, the description gives enough context for an agent to select and call the tool correctly. It could add operational side-effects like downtime or restart behavior, but those are not essential for the basic call.

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

  Parameters3/5

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

  The description names the main scaling dimensions (replicas, CPU, memory, storage), which maps well to the schema properties. However, it does not add details beyond what the schema descriptions already provide, and the required project/service parameters remain undocumented in the description. At 67% schema coverage, this is adequate but not exceptional.

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

  Purpose4/5

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

  The description names a specific action ('change') and the resources involved ('replica count, CPU, memory, or storage limits') for a Lizard service, making the tool's purpose clear. It does not explicitly contrast with sibling tools like service_set, but the field list and 'scale' title are enough to separate it from most alternatives.

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

  Usage Guidelines4/5

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

  It opens with explicit 'Use this when the user wants to change...', giving a clear trigger condition. It does not name alternatives or say when not to use this tool, but the phrasing provides adequate usage context for common scale requests.

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

• service_set_portA
  3.8/5.0
  Behavior3/5

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

  Annotations already establish readOnly=false, destructive=false, and idempotent=true. The description adds a small amount of context by saying the port is one the app 'listens on', but it does not explain any side effects such as whether the app needs to restart or whether the change takes effect immediately.

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

  Conciseness5/5

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

  The description is a single well-structured sentence with no filler. The usage trigger is front-loaded, and every word contributes to understanding.

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

  Completeness3/5

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

  For a simple setter with three flat parameters and no output schema, this is minimally adequate. An agent can likely infer project/service/containerPort from the names and context, but the 0% parameter schema coverage means the description alone leaves some ambiguity about what each argument represents.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It clarifies that 'containerPort' is the port the app listens on, but it provides no explanation of 'project' or 'service'. The parameter names are somewhat self-explanatory, but the description does not fully bridge the gap left by the undocumented schema.

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

  Purpose5/5

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

  The description uses a specific verb ('change') and identifies the exact resource ('the container port a Lizard app listens on'). It clearly differentiates from the sibling tool service_get_port, which is about reading rather than setting the port.

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

  Usage Guidelines4/5

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

  The description opens with 'Use this when the user wants to change...' which is a clear trigger condition. It does not explicitly mention alternatives or when not to use it, but the purpose is specific enough that an agent can infer when it applies.

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

• deploy_eventsA
  3.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the kind of data returned (deploy/build history and replica status), but does not disclose output shape, pagination, data freshness, or any limitations—making this acceptable but not exceptional.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that immediately states the intended use and the scope. Every element earns its place, and there is no redundant wording or repetition of the title.

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

  Completeness4/5

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

  For a relatively simple read-only tool with two string parameters and no output schema, the description covers the core purpose and the data area. Minor gaps exist around output format and what 'recent' means, but the description is sufficiently complete for an agent to select and invoke the tool correctly in most cases.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate for the two required parameters, project and service. It only indicates that the tool operates on 'a Lizard service,' which gives partial context for service but leaves project unexplained and does not clarify accepted value formats or relationships between parameters.

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

  Purpose5/5

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

  The description uses a specific verb ('see') and identifies the exact resource: 'recent deploy/build history and current replica status for a Lizard service.' It clearly distinguishes this read-oriented tool from sibling mutation tools like deploy_redeploy and deploy_restart by emphasizing history and status viewing.

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

  Usage Guidelines4/5

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

  The description explicitly states when to use the tool: 'Use this when the user wants to see recent deploy/build history and current replica status.' It provides clear context, though it does not explicitly name alternatives or state when not to use it.

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

• secrets_deleteA
  3.9/5.0
  Behavior4/5

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

  Annotations already flag destructiveHint=true, and the description adds meaningful context: the operation 'cannot be undone' and 'requires explicit confirmation.' This goes beyond the raw annotation and helps the agent understand the irreversibility and the need for user confirmation before invoking the tool.

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

  Conciseness5/5

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

  Two tightly written sentences with no filler. The usage trigger is front-loaded, and the destructive warning is placed immediately after. Every word earns its place.

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

  Completeness3/5

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

  For a simple deletion tool, the description covers purpose, destructiveness, and confirmation requirements. However, it does not clarify the project/service relationship or whether service-level deletion differs from project-level deletion, and there is no mention of return/error behavior. The destructive annotation helps, but the description leaves a few practical details unresolved.

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

  Parameters3/5

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

  Schema description coverage is only 25%, so the description carries more responsibility. It indirectly maps to parameters: 'one or more' implies the keys array, 'confirmation' maps to confirm, and 'service or project' points to project/service. However, it does not clearly explain the relationship between project and service (e.g., service is optional) or define the keys format, leaving some semantic gaps.

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

  Purpose5/5

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

  Description uses a specific verb ('remove') with a clear resource ('environment variables/secrets') and scope ('Lizard service or project'). This clearly distinguishes it from sibling tools like secrets_list and secrets_set, and there is no ambiguity about what action the tool performs.

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

  Usage Guidelines3/5

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

  The description opens with 'Use this when the user wants to remove...', giving a clear trigger condition. However, it does not mention alternatives or when not to use this tool, such as pointing to secrets_set for adding/updating secrets or secrets_list for viewing them, leaving sibling differentiation mostly implicit.

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

• service_get_portA
  3.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the Lizard app and listening port, but does not disclose return format or edge cases; with strong annotations this is acceptable but not rich.

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

  Conciseness5/5

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

  A single sentence that is front-loaded with the trigger condition and contains no filler. Every word contributes to understanding when and what the tool does.

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

  Completeness4/5

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

  For a simple read-only two-parameter lookup, the description conveys the purpose and the expected result adequately, and annotations cover safety. The main missing piece is parameter-level guidance, but overall the tool can be selected and invoked correctly.

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

  Parameters2/5

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

  The schema has two required string parameters with 0% description coverage. The description does not explain what project and service mean, their expected format, or how they relate to the port lookup, so it fails to compensate for the schema gap.

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

  Purpose5/5

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

  The description names a specific verb and resource: it tells the user which container port a Lizard app is listening on. This clearly differentiates it from service_set_port and other service-related siblings.

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

  Usage Guidelines4/5

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

  The description explicitly starts with 'Use this when...' and defines the exact condition for calling the tool. It does not mention alternatives or when not to use it, 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.

• service_showA
  3.9/5.0
  Behavior3/5

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

  Annotations already state readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds that the tool returns status, config, and resource limits, but does't disclose response format or behavior for a missing service, so it provides only modest additional behavioral context.

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

  Conciseness5/5

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

  A single sentence, front-loaded with the trigger condition, and every clause adds relevant qualification (single, app or addon, status/config/limits). No filler.

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

  Completeness4/5

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

  For a simple read-only show operation with rich annotations, the description covers when to use it and broadly what result to expect. It is slightly incomplete only in parameter semantics and lack of an explicit output shape.

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

  Parameters2/5

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

  Input schema has 0% description coverage and the description doesn't explain 'project' or 'service' beyond calling a service a Lizard app/addon. The names are suggestive, but for a tool with no parameter docs the description should compensate, and it mostly doesn't.

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

  Purpose5/5

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

  The description uses a specific verb ('details about') with a single resource type ('Lizard service') and enumerates the content (status, config, resource limits), which clearly separates it from sibling list and port-specific tools.

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

  Usage Guidelines4/5

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

  It explicitly frames when to use: 'Use this when the user wants details about a single Lizard service.' It doesn't mention when not to use or name alternatives, but the context is clear enough for a single-resource read operation.

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

• git_checkoutA
  4/5.0
  Behavior4/5

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

  Annotations already mark the tool as non-read-only and non-idempotent, but the description adds concrete behavioral detail: it returns immediately once the redeploy is triggered, and every call starts another build. This warns the agent about async completion and repeated side effects effectively.

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

  Conciseness5/5

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

  Three short sentences with no filler: the use case is front-loaded and the two behavior warnings are concise. Every sentence adds information an agent needs.

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

  Completeness3/5

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

  The description covers the primary use case, the return behavior, and the non-idempotent side effect, which is adequate for a simple three-parameter tool. However, it omits concrete parameter semantics and any validation or error constraints, so it is not fully complete without additional context.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not explain the project, service, or branch parameters or their expected values. The branch parameter is only vaguely implied by 'switch which branch a Lizard service deploys from', while project and service are left to be guessed from names alone. This does not compensate for the missing schema documentation.

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

  Purpose5/5

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

  The description clearly states a specific operation: switching the branch a Lizard service deploys from and redeploying on that branch. The verb 'switch' and the resource 'deploy branch' make the tool's purpose unambiguous and distinguish it from generic redeploy/restart tools.

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

  Usage Guidelines4/5

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

  It opens with 'Use this when the user wants to switch which branch...', which explicitly tells an agent when to invoke it. It does not mention alternatives or when not to use it, so it stops short of full exclusion/alternative guidance.

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

• metrics_getA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scope detail such as 'Lizard app or addon' and 'time range,' but it does not disclose return format or explain the 'live metrics' nuance beyond the schema. This is adequate but not rich.

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

  Conciseness5/5

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

  A single sentence that front-loads the use case and includes only essential information. No wasted or redundant wording.

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

  Completeness4/5

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

  This is a simple read-only metrics tool with rich annotations and an enum for range. The description plus schema gives an agent enough to select and call it correctly. The lack of an output schema means the response shape is not described, but that is a minor gap for a metrics-getting tool.

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

  Parameters3/5

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

  Schema description coverage is only 33%, so the description should compensate for undocumented parameters. The phrase 'app or addon' maps to the service parameter and 'over a time range' maps to range, but the required project parameter is not described in either the schema or the description. The range enum and service description in the schema carry part of the load.

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

  Purpose5/5

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

  The description names exactly what the tool does: retrieve CPU, memory, or network metrics for a Lizard app or addon over a time range. It is specific about both the resource type and the metric domains, and no sibling tool overlaps with this purpose.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this when the user wants CPU, memory, or network metrics,' giving a clear trigger condition. It does not list alternatives or when-not-to-use cases, but no sibling tool provides metrics, so this is sufficient context.

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

• service_listA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructoveHint, so the description's job is lighter. It adds context about listing 'all' apps and addons, but does not describe return format, pagination, or any behavioral nuances beyond the existing annotations.

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

  Conciseness5/5

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

  The description is a single sentence that directly states the purpose and scope. It is concise, front-loaded, and contains no filler or redundant information.

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

  Completeness4/5

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

  For a simple list tool with one parameter, safe annotations, and no output schema, the description is sufficient: it names the resource category (apps and addons) and the scope (a Lizard project). It could have mentioned whether the result is a list vs paginated, but the word 'all' and the tool name 'list' make the behavior clear enough.

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

  Parameters3/5

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

  Schema description coverage is 100% and the only parameter 'project' has a clear description. The tool description adds little semantic value beyond what the schema already provides, so the baseline of 3 applies.

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

  Purpose5/5

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

  Description states a clear verb ('see') and a specific resource ('all apps and addons in a Lizard project'). It also distinguishes itself from related tools like service_show, project_list, and workspace_list by specifying the scope of what is listed.

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

  Usage Guidelines4/5

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

  The description gives explicit guidance on when to use the tool: when the user wants to see all apps and addons. It does not explicitly exclude alternatives or mention when not to use it, but the usage context is clear enough for an agent to select this tool from the sibling set.

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

• deploy_restartA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=false and idempotentHint=false, so mutation and non-idempotency are known. The description adds useful specifics: it returns immediately, and every call triggers a restart even if called again immediately. This goes beyond the annotations and sets accurate expectations for repeated calls.

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

  Conciseness5/5

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

  Three short sentences, all carrying distinct value: when to use, immediate return behavior, and repeated-call semantics. No filler, no repetition of schema details, and the most actionable guidance is front-loaded.

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

  Completeness4/5

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

  The tool is simple with only two required parameters and annotations already cover the safety profile. The description covers the key behavioral concerns—immediate return and non-idempotency. It does not mention what happens if the service is not running or what the response contains, but the absence of an output schema and the simple nature of a restart make this gap minor.

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

  Parameters2/5

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

  Schema description coverage is 0% and the description adds no information about the 'project' or 'service' parameters beyond what the schema already provides via their names and minLength constraints. Although the parameter names are reasonably self-explanatory, the description does not compensate for the low coverage or clarify value formats.

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

  Purpose5/5

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

  States a specific action—restart a running Lizard service—and explicitly excludes rebuilding, which distinguishes it from any deploy/rebuild sibling. The verb+resource pairing is unambiguous and matches the tool name/title without being tautological.

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

  Usage Guidelines4/5

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

  Clearly says to use this tool when the user wants to restart a running Lizard service without rebuilding it. It implies the alternative is a rebuild/deploy path but does not name a specific sibling tool or give explicit when-not-to-use conditions beyond the no-rebuild distinction.

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

• domain_deleteA
  4.1/5.0
  Behavior4/5

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

  The annotations already indicate destructiveHint=true, but the description adds meaningful context by stating the action is destructive and requires explicit confirmation. This reinforces the safety warning and clarifies that no interactive confirmation exists, which is valuable behavioral information beyond the schema.

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

  Conciseness5/5

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

  Two concise sentences with no filler. The invocation condition and safety warning are front-loaded, making the description easy to scan and act on.

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

  Completeness4/5

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

  For a straightforward deletion tool, the description covers the key context: what is deleted, that it is destructive, and that confirmation is required. It does not describe return values, but no output schema exists and the operation's outcome is reasonably inferable. Minor missing details like hostname format or validation are not critical.

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

  Parameters2/5

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

  Schema description coverage is only 25%, with only 'confirm' described. The description does not explain the meaning or format of project, service, or hostname, relying on their names alone. Since the description does not compensate for the low schema coverage, parameter semantics are under-specified.

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

  Purpose5/5

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

  The description states a specific verb ('remove') and resource ('custom domain from a Lizard service'), making the tool's purpose immediately clear. It also distinguishes itself from siblings like domain_attach and domain_verify by focusing on deletion.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this when the user wants to remove a custom domain,' giving clear invocation context. It does not mention alternatives or when not to use it, but the domain-related sibling tools make the intended use fairly obvious.

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

• git_statusA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by specifying what information is returned (connection status and per-service repo/branch), but it does not disclose potential failure modes, output format, or operational nuances.

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

  Conciseness5/5

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

  A single sentence that front-loads the usage trigger and delivers the tool's purpose without filler. Every word earns its place, and the structure is optimally scannable.

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

  Completeness5/5

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

  For a read-only status tool with one simple parameter, the description covers the user intent, the input concept (project), and the returned information. No output schema exists, so the description's explicit mention of the output is sufficient.

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

  Parameters3/5

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

  Schema coverage is 0% and there is one required parameter, 'project'. The description references 'a Lizard project', which gives some semantic context for the parameter, but it does not explicitly define what a valid project value is or how it should be supplied. The compensation is partial.

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

  Purpose5/5

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

  The description uses a specific verb ('see') and names the exact resource: GitHub connection status and the repo/branch each service tracks. It clearly distinguishes itself from siblings like git_connect and git_checkout by focusing on status rather than action.

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

  Usage Guidelines4/5

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

  The description explicitly opens with 'Use this when the user wants to see...', which is a clear usage context. It does not explicitly name alternatives or exclusions, but the intent is unambiguous and the sibling set makes the differentiators obvious.

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

• service_deleteA
  4.1/5.0
  Behavior4/5

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

  Annotations already mark destructiveHint=true and readOnlyHint=false, and the description adds important context: deletion is permanent, cannot be undone, and requires explicit confirmation. It clearly communicates the irreversible nature beyond the bare annotation flags.

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

  Conciseness5/5

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

  The description is two dense sentences with no filler. The usage condition is front-loaded, and the destructive warning is placed immediately after, making the critical information easy to process.

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

  Completeness4/5

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

  For a destructive tool with three parameters and no output schema, the description covers the essential behavioral context: what is deleted, that it is permanent, and that confirmation is required. It could mention side effects or related resources, but the core information needed to invoke it safely is present.

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

  Parameters2/5

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

  Schema description coverage is only 33%, and the description does not explain the 'project' or 'service' parameters or their relationship. It adds some meaning by clarifying that a service is an app or addon and emphasizing confirmation, but it fails to fully compensate for the undocumented parameters.

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

  Purpose5/5

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

  The description uses a specific verb ('permanently delete') and resource ('Lizard service (app or addon)'), making the tool's function unambiguous. It also distinguishes this from sibling non-destructive operations like service_rename, service_scale, or deploy_restart.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this when the user wants to permanently delete a Lizard service,' which gives clear conditions for invocation. It does not explicitly contrast with alternatives or mention when not to use it, but the destructive, confirmation-required framing is sufficient for typical selection.

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

• billing_summaryA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds meaningful behavioral context by specifying that the summary includes 'current usage and live spend', implying real-time data rather than cached values. This goes beyond what annotations provide 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.

  Conciseness5/5

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

  The description is a single sentence of about 20 words that front-loads the usage condition and specifies the exact resource and data scope. There is no filler, repetition, or unnecessary detail.

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

  Completeness4/5

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

  For a simple one-parameter, read-only tool with no output schema, the description covers the essential selection and invocation information: when to use it, what it returns, and the target resource type. It could optionally describe return format or billing period, but nothing critical is missing for an agent to decide and call the tool correctly.

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

  Parameters3/5

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

  The schema has zero description coverage for workspaceId, so the description must compensate. It says 'for a Lizard workspace', which implies the parameter is the workspace identifier, but it never explicitly states that workspaceId should be the target workspace ID. Since there is only one parameter and its name is self-explanatory, the gap is limited, but the description still leans on the parameter name rather than explaining semantics.

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

  Purpose5/5

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

  The description opens with 'Use this when the user wants a cost/billing summary for a Lizard workspace', which clearly identifies the action (getting a summary), the resource (billing for a workspace), and the scope (current usage and live spend). This distinguishes it from sibling tools like metrics_get, which is about general metrics rather than billing.

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

  Usage Guidelines4/5

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

  The description explicitly states when to use the tool: when the user wants a cost/billing summary. It does not name alternatives or exclusions, but the condition is clear enough that an agent can route to it appropriately; the lack of explicit when-not guidance is a minor gap.

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

• deploy_redeployA
  4.2/5.0
  Behavior4/5

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

  Beyond what annotations provide (readOnlyHint=false, idempotentHint=false), the description discloses that the call returns immediately once the build is triggered, revealing an async fire-and-forget behavior. It also adds specific non-idempotence detail ('Each call starts another build, even if called again immediately') that reinforces and elaborates the idempotentHint=false annotation.

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

  Conciseness5/5

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

  Three sentences with zero waste. The first sentence front-loads purpose and trigger condition, the second discloses async return behavior and routes to deploy_events, and the third states non-idempotence. Every sentence earns its place.

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

  Completeness4/5

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

  For a low-complexity tool with 2 simple parameters and no output schema, the description covers purpose, when to use it, async behavior, non-idempotence, and the follow-up tool. It does not describe what the immediate return payload looks like or what happens if the build fails, but these are minor given the simplicity of the operation.

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

  Parameters3/5

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

  Schema coverage is 0%, so the description carries the burden, and it partially compensates: the word 'existing' implies the service parameter must already exist (not create), and 'current source' implies the deployment uses the current code state. However, it does not explicitly define what project and service refer to; the parameter meanings are mostly left to inference from context.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'trigger a new deployment of an existing Lizard service (rebuild and redeploy current source)'. The parenthetical clarifies the exact scope of the action, distinguishing it from a mere restart. It clearly separates this from deploy_events, which is for progress checking.

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

  Usage Guidelines4/5

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

  The description opens with an explicit trigger condition ('Use this when the user wants to trigger a new deployment of an existing Lizard service') and names a concrete alternative for a related need ('use deploy_events to check progress'). However, it does not explicitly say when NOT to use this tool versus the sibling deploy_restart, leaving that contrast to inference.

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

• logs_tailA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context by clarifying that the result is a bounded snapshot rather than a live stream, which is genuinely useful beyond the annotations.

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

  Conciseness5/5

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

  The description is two sentences with no filler. The primary usage scenario is front-loaded, and the live-stream clarification adds important information without bloating the text.

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

  Completeness4/5

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

  The description plus schema and annotations cover the essential invocation context for a read-only log retrieval tool. It could be slightly more complete by stating what the returned snapshot looks like, but the bounded-snapshot phrase largely covers that expectation.

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

  Parameters3/5

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

  Schema description coverage is 50%, and the description does not go into parameter-level details. It gives context about 'service' and 'build' but leaves limit, project, and service semantics mostly to the schema or obvious naming, so the added value here is moderate.

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

  Purpose5/5

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

  The description clearly states the tool's action: see recent log output from a Lizard service or a specific build. It also differentiates the behavior by noting it returns a bounded snapshot, not a live stream, which distinguishes it from a typical 'tail' tool.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this when the user wants to see recent log output', which provides clear context for when to invoke it. It does not name alternative tools or exclusion cases, but the intended scenario is unambiguous.

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

• project_createA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate non-idempotent and non-read-only behavior; the description adds useful concrete detail: calling again creates another project even with the same name, and does not update an existing one. This exceeds what the annotations alone convey, though it does not mention permissions or what the response contains.

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

  Conciseness5/5

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

  Two tightly written sentences, both useful: the first gives the purpose and usage context, the second warns about duplicate creation/non-update behavior. No filler or repetition of schema fields.

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

  Completeness4/5

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

  For a simple two-parameter create tool, this is reasonably complete: purpose, usher intent, and the key non-idempotence caveat are covered. It does not describe the return value or behavior on invalid workspaceId, but no output schema exists and the annotations cover the safety profile.

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

  Parameters3/5

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

  Both parameters have descriptions in the schema ('Project name', 'Workspace to create the project in'), so schema coverage is 100%. The description does not add substantial meaning beyond those schemas; it mentions the project is empty and holds services, which only loosely relates to parameters.

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

  Purpose5/5

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

  Description uses a specific verb ('create') and resource ('brand-new empty Lizard project to hold services'), clearly distinguishing this from sibling service_create and addon_create tools. The phrase 'brand-new empty' also clarifies that the tool does not modify existing projects.

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

  Usage Guidelines4/5

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

  Accurately states when to use the tool: when the user wants a brand-new empty Lizard project. It does not explicitly enumerate when not to use it or name alternatives such as service_create, so it stops short of full exclusion guidance, but the use case is clear and not misleading.

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

• secrets_listA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds important behavioral detail: values are masked by default and reveal:true is required to see actual values. This is beyond the annotations and directly relevant to invoking the tool.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the usage trigger and followed by the key behavioral caveat. Every sentence earns its place with no redundant detail.

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

  Completeness4/5

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

  For a simple read-only list tool with no output schema, the description covers when to use it, the service/project scoping, and the masking behavior. A hint about the exact return shape would be nice, but the title and description carry the agent far enough.

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

  Parameters3/5

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

  Schema description coverage is only 33%, so the description must compensate. It adds meaning for 'reveal' and clarifies that secrets are scoped to a service or project, but it does not describe the 'project' parameter semantics directly, and the schema already documents the optional-service nuance. Partial compensation, but with a clear gap.

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

  Purpose5/5

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

  The description clearly states the operation ('see environment variables/secrets') and its resource scope ('configured for a Lizard service or project'). This distinguishes it from sibling tools like secrets_set, secrets_delete, and secrets_refs, which involve different actions.

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

  Usage Guidelines4/5

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

  The phrase 'Use this when the user wants to see...' gives an explicit usage trigger. It does not mention exclusions or alternatives, but the context is clear enough for an agent to select this tool for listing secrets.

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

• secrets_setA
  4.2/5.0
  Behavior4/5

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

  The annotations already provide idempotentHint=true and destructiveHint=false, and the description adds the important effect that existing values with the same key are overwritten. This goes beyond the annotations and gives the agent useful behavioral context.

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

  Conciseness5/5

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

  Two sentences with no filler. The primary use case is front-loaded and the key overwrite behavior is stated in a compact second sentence.

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

  Completeness4/5

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

  For a straightforward set operation, the description covers when to use it, the target scope, and the overwrite behavior. It does not describe the return value or whether setting secrets triggers a redeploy, but these are not essential for invoking the tool correctly given the schema and annotations.

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

  Parameters3/5

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

  The input schema covers values and service with descriptions, giving 67% coverage. The description broadly maps to the project and service parameters by mentioning 'Lizard service or project', but it does not add meaningful detail about the values object or the project parameter beyond what the schema already states.

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

  Purpose5/5

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

  The description states a specific verb ('set') and resource ('environment variables/secrets') with a clear scope ('Lizard service or project'). This clearly distinguishes it from sibling tools like secrets_list and secrets_delete.

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

  Usage Guidelines4/5

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

  The description opens with 'Use this when the user wants to set...', giving a direct usage condition. It does not explicitly name alternatives or exclusions, but the action of setting secrets is unambiguous relative to the sibling tools.

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

• domain_attachA
  4.3/5.0
  Behavior4/5

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

  Annotations already mark this as non-read-only and non-idempotent. The description adds useful context beyond that: every app gets an automatic domain on first deploy, service_show should be checked first, and repeat hostname-less calls generate additional subdomains. This is meaningful behavioral disclosure, though it does not describe side effects of the force flag.

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

  Conciseness4/5

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

  Three dense sentences with the most important guidance front-loaded. The first sentence is long and parenthetical, but each clause carries a necessary constraint rather than filler.

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

  Completeness4/5

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

  For a mutating tool with no output schema and five parameters, this description provides strong operational context: when to call, what to check first, and how to avoid the duplicate-subdomain trap. It lacks post-call verification guidance and port semantics, but these are minor compared to the upfront guardrails.

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

  Parameters3/5

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

  The description adds real meaning for hostname by distinguishing custom vs generated subdomains, but hostname and force already have schema descriptions. Required project/service and optional port receive no explanation, and with only 40% schema coverage the description only partially compensates for the undocumented port parameter.

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

  Purpose5/5

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

  The description makes clear the tool attaches either a user-supplied custom hostname or generates a default *.onlizard.com subdomain. It explicitly distinguishes this from the automatic domain assigned at first deploy and references service_show, so an agent can tell it apart from domain_verify/domain_delete.

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

  Usage Guidelines5/5

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

  It states exactly when to call: only for an explicit custom domain request, or when service_show shows no domain yet. It also gives a clear negative constraint — do not invent or guess a hostname — and warns against repeated calls without a hostname generating new subdomains instead of returning the existing one.

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

• region_listA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the 'before creating' use case but does not describe the return format or any other behavioral traits. This is acceptable for a simple zero-parameter read-only list tool, but it does not go beyond the annotations in a significant way.

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

  Conciseness5/5

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

  The description is a single clear sentence that states the use case immediately. There is no redundant wording or unnecessary detail.

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

  Completeness5/5

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

  For a zero-parameter, read-only, idempotent list tool, the description is complete. It tells the agent when to invoke it and what the user will learn. No output schema exists, but the simple nature of the tool makes this acceptable.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema is trivially complete and there is nothing for the description to explain. Baseline 4 is appropriate because no parameter documentation burden exists.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: informing the user which deployment regions are available. It names a specific resource (regions) and a specific context (before creating a service or addon), distinguishing it from sibling list tools like workspace_list, project_list, and service_list.

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

  Usage Guidelines4/5

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

  The description explicitly says when to use the tool: when the user needs to know available regions before creating a service or addon. It does not discuss alternatives or exclusions, but there are no obvious sibling region tools, so the guidance is sufficient for this simple tool.

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

• whoamiA
  4.3/5.0
  Behavior3/5

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

  Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description does not need to restate those. It adds the useful context that the tool exposes the currently authenticated identity, but does not describe any further behavior such as response shape or permissions.

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

  Conciseness5/5

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

  A single sentence that front-loads the usage condition immediately. Every word contributes clarii: the action, the target, and a concrete example.

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

  Completeness5/5

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

  For a zero-parameter, read-only identity tool, the description is complete: it explains when to use it and what it returns conceptually. Annotations supply the safety profile and no output schema is necessary for such a simple operation.

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

  Parameters4/5

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

  There are zero parameters and schema description coverage is 100%, so no paramter explanation is required. Baseline for no-parameter tools is 4; the description adds no unnecessary paramter noise.

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

  Purpose5/5

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

  The description uses a specific verb, 'identify,' with a clear resource, the currently authenticated Lizard user. It is immediately distinguishable from all sibling tools, which focus on deployment, billing, secrets, projects, services, and git operations.

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

  Usage Guidelines4/5

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

  It explicitly states when to use the tool: whenever the agent needs the authenticated Lizard user, with a concrete example ('before asking which workspace or project to act on'). No alternative identity tool exists among siblings, so exclusion/alternative guidance is unnecessary.

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

• addon_createA
  4.4/5.0
  Behavior5/5

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

  Annotations declare idempotentHint=false and readOnlyHint=false, and the description enriches this abstraction with concrete behavior: 'Calling this again creates another addon, even with the same name — it does not update an existing one.' This prevents a common LLM failure mode of assuming create calls are idempotent or upsert-like. No contradiction with any annotation.

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

  Conciseness5/5

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

  Two sentences with no filler; the purpose is front-loaded in the first sentence and the critical non-idempotency warning lands in the second. Every clause earns its place.

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

  Completeness4/5

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

  Required parameters and enum values are encoded in the schema, and the region schema comment already routes agents to region_list. The description supplies the one behavioral fact that matters most — repeated calls create duplicates — which the annotations only convey abstractly. With no output schema and a simple flat structure, nothing essential is missing, though post-creation results or next steps are unspecified.

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

  Parameters3/5

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

  Schema coverage is 50%: region and name have descriptions, while type and project are undocumented. The description's parenthetical '(Postgres, Redis, or S3)' merely restates the schema's type enum and adds no meaning beyond it, and it does not compensate for the missing project semantics. However, the phrase 'Lizard project' provides a small domain hint for what project refers to.

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

  Purpose5/5

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

  States a specific verb ('provision') and resource ('managed database or storage addon') with concrete types enumerated in parentheses (Postgres, Redis, S3), and scopes it to a Lizard project. The second sentence adds that the tool always creates a new addon, clarifying what it is not (an update tool). This distinguishes it from sibling creation tools like service_create without needing to inspect the schema.

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

  Usage Guidelines4/5

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

  Opens with an explicit 'Use this when the user wants to provision a managed database or storage addon...' which gives a clear activation condition. The scoping to Postgres/Redis/S3 addons implicitly separates it from service_create and other creation siblings, but it names no alternative tool or when-not-to-use condition explicitly.

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

• config_applyA
  4.4/5.0
  Behavior4/5

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

  Annotations already mark destructive=true; description adds concrete context that the config body is passed through verbatim and can overwrite or remove existing fields. This usefully warns an agent about potential data loss. It does not describe rollback, failure modes, or permission requirements, but the destructive warning is well covered.

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

  Conciseness5/5

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

  Two sentences, with the key usage context front-loaded and the alternative tool guidance placed directly afterward. No filler or redundant restating of the tool name.

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

  Completeness4/5

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

  For a destructive, arbitrary-body tool, the description covers when to use it, what it does, and what to use instead for single-field changes. It does not mention return values or what happens after apply, but no output schema exists and the use-case guidance is strong.

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

  Parameters3/5

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

  Schema coverage is only 50%: config has a description, project does not. The description adds useful semantics for config (multiple services/addons/secrets at once, overwrite/remove behavior), but it does not clarify the project parameter format or the actual config shape an agent should send. It partially compensates for the schema gap but leaves room for ambiguity.

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

  Purpose5/5

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

  The description names a specific operation: applying bulk, config-as-code style configuration to a Lizard project in one request. It explicitly contrasts this with changing one field at a time, making it easy to distinguish from narrower sibling tools like service_set and secrets_set.

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

  Usage Guidelines5/5

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

  The description starts with 'Use this when...' and explicitly says to prefer the narrower service.*/secrets.* tools for single-field changes. This gives clear when-to-use and when-not-to-use guidance.

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

• ssh_execA
  4.4/5.0
  Behavior5/5

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

  The description goes beyond annotations by warning that the tool 'executes arbitrary code in the user's own infrastructure on their behalf' and requires explicit confirmation. It also discloses that it waits for command completion. This is critical behavioral and safety context that annotations alone do not fully express.

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

  Conciseness5/5

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

  The description is concise and front-loaded with the primary use case, followed by the behavioral guarantee and risk/confirmation warning. Every sentence adds necessary information with no filler.

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

  Completeness4/5

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

  For a command execution tool with four required parameters and no output schema, the description covers what it does, when to use it, that it waits, and that confirmation is mandatory. It does not describe the exact output format or timeout behavior, but the essentials for selecting and invoking the tool correctly are present.

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

  Parameters3/5

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

  The schema already describes cmd and confirm well. The description adds context that the target is a running Lizard service's container, which gives project and service some semantic grounding. However, it does not explain how to determine or format project and service values, and half the parameters have no schema description, so the description only partially compensates.

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

  Purpose5/5

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

  The description clearly states the tool runs a one-off shell command in a running Lizard service container and returns its output. It uses a specific verb and resource, and this is distinct from sibling tools like deploy_restart, logs_tail, or git_connect, so an agent can confidently distinguish it.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this when the user wants to run a one-off shell command,' which gives clear invocation context. It also notes it waits for the command to finish, implying synchronous behavior, and states confirmation is required. It does not list exclusions or alternatives, but there are no closely similar sibling tools that would require an explicit when-not-to-use.

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

• workspace_listA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context by clarifying that the result is limited to workspaces the user belongs to, which helps set expectations about the returned data without relying on structured annotations.

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

  Conciseness5/5

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

  A single sentence carries both the usage trigger and the scope of results with no filler. The information is front-loaded and every word earns its place.

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

  Completeness5/5

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

  For a parameterless, read-only listing tool, the description fully covers when to call it and what it returns conceptually. Annotations cover safety and idempotency, and no output schema is present to clarify further. Nothing material is missing.

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

  Parameters4/5

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

  The tool has zero parameters and the schema is empty, so there is no parameter complexity to document. The description therefore does not need to compensate for schema gaps; the baseline for a parameterless tool is appropriate here.

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

  Purpose5/5

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

  The description states a specific verb (list) and resource (Lizard workspaces), and further narrows the scope to workspaces the user belongs to. It also identifies a concrete downstream purpose (obtaining a workspace ID for project lookups), which distinguishes it from other list tools like project_list and service_list.

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

  Usage Guidelines4/5

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

  The description begins with 'Use this when' and gives two explicit triggers: viewing workspaces the user belongs to, or needing a workspace ID for a project lookup. It does not name alternatives or state when not to use it, but the triggers are clear enough to guide selection among sibling tools.

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

• git_connectA
  4.7/5.0
  Behavior5/5

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

  Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful behavior beyond those hints: it returns a URL and cannot complete the connection automatically. This prevents an agent from assuming the action is finished after invocation.

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

  Conciseness5/5

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

  Two concise sentences with no filler. The usage trigger is front-loaded, and the critical behavioral caveat about manual browser opening is stated immediately. Every sentence earns its place.

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

  Completeness5/5

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

  For a zero-parameter, read-only tool that returns a URL, the description covers when to use it, what it returns, and the essential follow-up action. 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.

  Parameters4/5

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

  The tool has zero parameters and schema coverage is 100%, so there is nothing more to document. The description does not need to explain parameter meaning; the baseline score for a parameterless tool applies.

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

  Purpose5/5

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

  The description states a specific action and resource: connecting the user's GitHub account to Lizard, and explicitly says the tool returns an install URL. This clearly distinguishes it from sibling tools like git_checkout or git_status, which deal with repositories rather than account linking.

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

  Usage Guidelines4/5

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

  The description gives an explicit trigger ('when the user wants to connect their GitHub account') and adds the important constraint that the URL must be opened by the user manually. It does not name alternatives or exclusions, but no sibling tool appears to offer a comparable connection flow.

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

• service_createA
  4.7/5.0
  Behavior5/5

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

  Despite annotations already marking idempotentHint=false, the description adds concrete non-idempotency detail: calling again creates another service even with the same name. It discloses the async domain-assignment behavior (domain null until build/boot, expected not an error) and an error-prevention rule (do not invent/guess a hostname), all of which go well beyond the annotation flags. 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.

  Conciseness4/5

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

  A single ~150-word paragraph with no filler; every sentence delivers load-bearing behavioral or usage information. It is front-loaded with the use case and follows a logical order (when → how → caveats → follow-up). Slightly long and wall-of-text formatted, but justified by the density of critical guidance.

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

  Completeness4/5

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

  For a state-changing 7-param create operation with no output schema, the description covers the high-risk failure modes: non-idempotency, async domain assignment (naming the response's `domain` field explicitly), and the correct follow-up workflow. Minor gaps remain — it never summarizes the broader response shape or the semantics of envVars/containerPort — but the critical decision and error paths are fully covered.

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

  Parameters4/5

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

  Schema coverage is 57%, so the description carries some burden for undocumented params (project, envVars, containerPort). It adds real strategic meaning for repoUrl — the two-mode decision (empty vs immediate deploy) that determines whether to populate repoUrl and skipInitialDeploy — beyond the schema's one-line property description. It does not, however, compensate for the three schema-undocumented parameters.

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

  Purpose5/5

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

  The description names a specific verb-resource pair — create a new Lizard service — and enumerates two concrete modes: empty service versus deploy-from-GitHub-repo. It further disambiguates from siblings by stating it never updates an existing service, which separates it from service_set/service_rename. An agent can tell exactly what this tool does and roughly what it is not.

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

  Usage Guidelines5/5

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

  Opens with an explicit 'Use this when the user wants to...' scoping rule and gives a decision rule between the two modes (omit repoUrl vs provide it). It states an exclusion — 'it does not update an existing one' — and names concrete alternative tools (service_show, deploy_events) for the follow-up polling flow. 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.