northflank

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

Annotations already declare readOnlyHint=true, indicating a non-mutating operation. The description adds the phrase 'details and status', hinting at the returned content, but does not go beyond that. No additional behavioral context (e.g., error behavior, rate limits, or side effects) is provided. Since the annotation covers the safety profile, 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.

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

The description is two short sentences that are front-loaded with the core purpose and include the exact REST endpoint. Every word is useful; there is no fluff or redundancy. It is concise and well-structured.

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

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

For a simple GET-by-ID tool with two fully described parameters and a readOnlyHint annotation, the description is complete. It tells the agent what the tool does and provides the API reference. The agent can call it correctly without needing additional behavioral details, and the lack of an output schema is acceptable since return formats are not required.

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

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

Schema description coverage is 100%, so both parameters (projectId and addonId) are fully documented in the schema, including a hint that addonId comes from northflank_list_addons. The description itself adds no parameter-specific meaning beyond restating the endpoint placeholders. This meets the baseline for high schema coverage.

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

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

The description clearly states 'Get details and status of a single addon', specifying the verb (get), the resource (addon), and scope (single). It is unambiguous and distinct from sibling tools like list_addons or get_project, which are named differently. The inclusion of the HTTP endpoint reinforces the exact operation.

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

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

The description implies usage for retrieving a single addon but does not explicitly contrast with alternatives or provide when-not scenarios. It does not mention that list_addons should be used to enumerate addons, nor does it state exclusions (e.g., 'for multiple addons use northflank_list_addons'). The usage context is clear enough for inference, but explicit guidance is missing.

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

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

The annotations already declare readOnlyHint: true, so the safety profile is covered. The description adds the response content (build/deploy config and cron schedule), which gives useful context about what to expect. It doesn't describe any side effects or error behavior, but for a read-only operation this is adequate.

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

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

The description is two sentences with no wasted words. It front-loads the action and the key content, then adds the REST endpoint for precision. It is highly efficient and structured for quick comprehension.

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

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

For a simple get-by-id tool with two required parameters and no output schema, the description provides enough context: it states what the tool returns and is unambiguous. It doesn't mention return format details, but that's not essential for a single-job fetch when annotations and schema cover the rest.

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

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

Schema coverage is 100% with both parameters having descriptive text. The tool description itself does not add any parameter-level semantics beyond the schema. Since the schema fully documents the parameters, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool gets details of a single job, and specifies exactly what details are included (build/deploy config and cron schedule). It distinguishes itself from sibling tools by focusing on jobs, and the REST endpoint reinforces the resource being accessed.

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

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

The usage is implied: when you need job details, use this tool. However, there is no explicit guidance on when not to use it or mention of alternatives like get_service or get_addon. For a simple getter this is acceptable but could be clearer about exclusion criteria.

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

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

Annotations already mark this as readOnlyHint=true, and the description reinforces this with GET semantics. It adds useful behavioral context by saying the response includes region, cluster, and associated services/jobs/addons, going beyond a bare 'get'. No destructive or hidden side effects are suggested.

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

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

Two short sentences with no filler: the first gives the action and scope, the second gives the endpoint. The behavioral description is front-loaded and every clause earns its place.

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

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

For a simple read-only detail tool, the description plus schema and annotations are sufficient: the target resource, ID source, and general response contents are covered. With no output schema, the response-content hint is valuable, though error/not-found behavior is not mentioned.

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

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

The single projectId parameter is fully documented in the schema, including its source from northflank_list_projects, so schema description coverage is 100%. The description's endpoint template adds no further parameter meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description states an explicit verb and resource: 'Get details of a single project'. It also enumerates the included scope (region, cluster, associated services/jobs/addons) and provides the endpoint. This clearly distinguishes it from sibling tools like northflank_get_service or northflank_list_projects.

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

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

The tool is clearly scoped to fetching one project by ID, and the schema further says projectId comes from northflank_list_projects, implying the intended workflow. It does not explicitly name alternatives or state when not to use it, but the resource-specific description makes the usage context obvious.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with a GET endpoint and 'current status' context. However, it adds no depth about response format, error behavior, or other operational traits beyond this.

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

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

Two compact sentences with no filler. The key action and object are front-loaded, and the endpoint line gives precise REST context without redundancy.

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

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

Adequate for a simple, read-only two-parameter tool: the operation, endpoint, and schema cover most needs. It could be more complete by hinting at the returned payload shape, especially since there is no output schema, but this is a minor gap.

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

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

Schema description coverage is 100%, so projectId and serviceId are already well documented. The description adds no additional parameter-level meaning, which is acceptable given the schema baseline.

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

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

States a specific verb and resource: 'Get details and current status of a single service.' This clearly differentiates from list_services, get_addon, get_job, and get_service_metrics. The REST path reinforces the exact scope.

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

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

Implies usage when a single service's details/status are needed, but does not explicitly say when not to use it or mention alternatives. It does not guide the agent to list_services for discovering IDs or to get_service_metrics for metric-specific data.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: it targets containers, returns CPU/memory metrics, and supports two distinct query modes. It does not cover response shape or rate limits, but the read-only safety profile is already covered by annotations.

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

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

Two focused sentences front-load the core purpose, include the endpoint, and then give mode-specific usage guidance. There is no filler or redundant restatement of schema fields.

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

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

With 8 parameters, all schema-documented, and read-only annotations, the description provides enough context to invoke the tool correctly. It is missing an explicit note about the response format, which matters because there is no output schema, but this is a minor gap rather than a blocking omission.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how queryType relates to the time parameters, and by clarifying that single is the default mode. This helps an agent select and combine parameters correctly.

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

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

The description uses a specific verb ('Get') and resource ('CPU / memory metrics for a service's containers'), and includes the REST endpoint. This clearly differentiates it from sibling tools like get_service or list_services, which are not metric-focused operations.

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

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

It does not explicitly name sibling alternatives, but it gives clear invocation guidance by explaining queryType=single for a current snapshot and queryType=range with duration/startTime/endTime. This is sufficient context for deciding how to use the tool, with no conflicting exclusions.

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

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

Annotations already provide readOnlyHint=true, so the read-only nature is disclosed externally. The description adds that the response includes status, which is useful, but does not elaborate on pagination behavior, result ordering, or response shape beyond what the schema already indicates. It neither contradicts nor significantly extends the annotation-provided behavior.

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

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

The description is a single, compact sentence that front-loads the core purpose, adds clarifying detail in parentheses, and ends with the HTTP endpoint for reference. There is no redundant or filler content; every phrase earns its place.

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

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

For a list operation with full schema coverage and a readOnlyHint annotation, the description is largely complete. It identifies the resource, scope, and included status field. The only minor gap is that it does not explicitly describe the overall response structure (e.g., an array of addon objects), but this is a list endpoint and the title conveys that sufficiently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-related meaning beyond the schema: it mentions projectId implicitly via the endpoint but does not explain pagination parameters or their semantics. Since the schema already fully documents all four parameters, the description does not need to compensate.

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

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

The description clearly states the verb 'List', the resource 'addons', and clarifies that these are 'managed databases / services' scoped to 'a project'. It also mentions 'with their status', providing additional specificity. This distinguishes it from the sibling northflank_get_addon, which retrieves a single addon, and from other list_* tools which target different resources.

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

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

The description implies when to use the tool: when you need to enumerate addons within a project. However, it does not explicitly contrast with northflank_get_addon or state when not to use this tool in favor of alternatives. The usage context is clear but not proactive about routing away from siblings.

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

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

Annotations already declare readOnlyHint=true, covering the read-only safety profile. The description adds that domains are returned with verification status and that team scoping changes the endpoint, but it does not disclose response shape or pagination behavior.

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

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

Two short sentences with no filler. The main capability is front-loaded, and the endpoint note provides useful API mapping without bloating the description.

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

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

Given the read-only annotation, full parameter coverage, and straightforward list operation, the description supplies enough information to select and invoke the tool. It names the resource, scope, endpoint variants, and verification-status output. It could mention the paginated response shape, but the schema's cursor and per_page parameters already signal pagination.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description adds only account-versus-team context and endpoint mapping, which does not materially go beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('List'), names the resource ('custom domains'), and clarifies scope ('account (or a team)'). It also notes that results include verification status, which distinguishes it from sibling list_* tools targeting other resources.

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

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

It provides clear context for account-level versus team-scoped usage, including the teamId endpoint variant. It does not explicitly state when not to use it or name an alternative, but no sibling tool duplicates the domains resource, so selection is straightforward.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation, lowering the bar. The description adds that the tool returns both manual and cron jobs, which is mild behavioral context, but does not disclose pagination details, authentication requirements, or what happens when no jobs exist.

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

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

A single efficient sentence that states the tool's purpose, the job type qualification, and the underlying endpoint. No filler or redundant phrasing.

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

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

For a straightforward list operation with full schema coverage and a readOnlyHint, the description is nearly complete. The absence of an output schema is acceptable since it is a list endpoint, though a brief note on pagination or that it returns an array might have made it fully self-contained.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's endpoint references {projectId}, which contextualizes that it is a path parameter, but it adds no meaning for page, cursor, or per_page beyond the schema.

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

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

The description clearly states the operation ('List jobs') and the resource scope ('in a project'), and further specifies the job types ('manual / cron'). The explicit endpoint 'GET /v1/projects/{projectId}/jobs' and use of 'List' differentiate it from sibling get_job, making the purpose obvious.

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

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

The context for when to use this tool is implied by 'List jobs' and the project scope, but there is no explicit guidance distinguishing it from alternatives like northflank_get_job or northflank_list_services. No exclusions or conditions are provided.

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

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

Annotations already provide readOnlyHint=true. The description adds useful context about token scope and the team-specific endpoint, but does not disclose pagination behavior beyond what the schema already documents.

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

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

Two concise, front-loaded sentences convey the purpose, scope, use case, and endpoint with no wasted words.

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

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

The description is sufficient for a simple list operation with no required parameters and read-only annotations. It implies the response contains project IDs, though it does not detail the return shape, which is acceptable given the tool's simplicity.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds no extra parameter-level meaning, matching the baseline.

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

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

Description clearly states the verb (List), resource (projects), and scope (authenticated token or a team). It also names the HTTP endpoint, which distinguishes it from sibling get_/list_ tools.

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

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

Explicitly frames the tool as a good first call for discovering project IDs, which gives concrete usage context. It does not explicitly mention alternatives like get_project for single-project lookups, so there are no exclusions.

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

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

Annotations already convey readOnlyHint=true, and the description reinforces and expands on this by specifying metadata-only fields and excluding secret values. It also supplies the endpoint, giving the agent expected behavior without contradicting annotations.

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

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

The description is two sentences, front-loads the core purpose and key limitation, and includes the endpoint without unnecessary verbiage. Every phrase earns its place.

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

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

With no output schema, the field list and no-values warning give the agent a concrete model of the response. Pagination shape is left implicit, but the schema documents the pagination parameters, so the description is largely complete for invocation.

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

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

Schema coverage is 100%, so parameters are already fully documented. The description adds little parameter-level detail beyond identifying projectId in the endpoint; baseline 3 applies.

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

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

The description opens with a specific verb-resource pair ('List a project's secret groups'), then sharpens scope with 'METADATA ONLY' and names the returned fields. It also disambiguates from any secret-value tool by stating 'Does NOT return secret values.'

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

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

It clearly frames when to use the tool: to retrieve project secret-group metadata. The explicit warning that it does not return secret values tells an agent this is not the tool when values are needed, though no alternative tool is named.

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

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

The readOnlyHint annotation already covers the safety profile, and the description aligns with it by describing a read operation. The description adds some context about what the response history includes (branch, sha, status, timestamps) and the HTTP endpoint, but it does not disclose pagination behavior, rate limits, or what happens when no builds exist. This is acceptable but not unusually transparent.

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

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

One concise sentence immediately states the purpose and expected fields, followed by the endpoint for orientation. There is no fluff or repetition of the parameter schema, making every word useful.

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

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

For a list endpoint with a rich schema and readOnlyHint annotation, the description is nearly sufficient. It tells the agent what is being listed and a bit about the contents. It does not mention pagination explicitly, but the schema covers page, cursor, and per_page, so the missing piece is only a minor clarification rather than a critical one.

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

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

Schema description coverage is 100%, so all five parameters already have meaningful descriptions in the input schema. The description does not add parameter-level detail beyond restating the endpoint placeholders, which provides no additional semantic value. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description clearly identifies the operation: listing a build service's build runs/history, including specific data fields (branch, sha, status, timestamps). The verb 'list' plus the resource 'build service's build runs' is specific and distinct from sibling tools that list services, jobs, or addons.

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

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

The description does not explicitly state when to choose this tool versus alternatives such as northflank_list_services or northflank_get_service. The endpoint path implies it targets build/combined services, but there is no direct guidance on when this is the right tool or what conditions make it preferable.

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

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

Annotations already declare readOnlyHint=true, and the description's GET endpoint is consistent with that. It adds modest value by clarifying results include build+deployment status and that both build and deployment service kinds are covered. It does not disclose pagination semantics (page vs cursor interplay) or result shape, but with a safety annotation present, the bar is lower and no contradiction exists.

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

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

Two tight sentences: the functional statement is front-loaded and the endpoint adds a compact verifiable detail. The endpoint is slightly redundant given readOnlyHint=true and the verb 'list', but it is a single low-cost clause, making the whole definition efficient.

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

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

For a read-only list operation with fully documented parameters and a safety annotation, the description covers what is listed, the scoping project, the status payload, and the HTTP contract. With no output schema present, the agent still lacks explicit return-shape information, but the description hints at it adequately for a list tool of this complexity.

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

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

Schema coverage is 100%, so per calibration the baseline is 3. The description's mention of 'in a project' and the endpoint path reinforce projectId's role as the scope identifier, but it adds no new meaning for page, cursor, or per_page beyond what the schema already documents clearly.

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

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

States a specific verb (list), resource (services), and scope (in a project), plus informative detail on the three included types (build / deployment / combined) and that build+deployment status is returned. It is clearly a collection-read rather than a single-resource fetch, but it doesn't explicitly name siblings like get_service or list_service_builds to draw the boundary.

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

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

The context of use is implied: listing services in a project, with pagination parameters documenting how to page through. However, there is no explicit guidance on when to choose this over northflank_get_service (single service) or northflank_list_service_builds (build history), nor any exclusion criteria. An agent must infer routing from sibling names.

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

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

Annotations already mark destructiveHint=true, and the description adds the behavioral detail that pausing scales to zero running instances and is a mutating operation. This gives an agent more context than the annotation alone, though it does not discuss reversibility or side effects; still, the added context is meaningful.

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

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

The description is a single sentence that front-loads the mutating nature, states the action, and includes the endpoint. Every word earns its place with no redundancy or filler.

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

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

For a simple two-parameter tool with no output schema and no nested objects, the description is sufficient. It communicates the operation, the effect, and the HTTP method, and the annotations cover the destructive flag. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%: both projectId and serviceId have simple descriptions ('Project id.', 'Service id.'). The tool description adds no extra semantics for these parameters. Per the calibration baseline, a 3 is appropriate when the schema already documents all parameters.

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

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

The description states a specific verb ('pause') and resource ('service'), and adds a precise effect ('scaling it to zero running instances'). This clearly distinguishes it from sibling tools like resume, restart, or scale, and the HTTP endpoint provides additional unambiguous context.

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

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

The action is clearly defined, and the name/description make it obvious when to call it. However, it does not explicitly mention that resume_service is the counterpart or call out scenarios where an alternative (e.g., scale_service to zero) could be used instead, so it misses the highest bar for explicit guidance.

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

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

Annotations already declare destructiveHint=true, so the mutating nature is covered. The description adds useful context that all running containers are restarted and gives the exact endpoint, but it does not disclose potential downtime, side effects, or whether configuration is preserved. No contradiction with annotations.

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

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

Extremely concise and front-loaded: it opens with a clear MUTATING warning, states the action and scope, then provides the endpoint. Every element earns its place.

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

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

For a simple two-parameter mutation, the description covers the action, scope, endpoint, and destructive nature. The only gaps are notes on post-restart behavior or response details, but the tool's low complexity keeps these omissions minor.

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

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

The schema already documents both parameters with simple descriptions, so coverage is 100%. The description only restates parameter names in the endpoint path and adds no additional meaning about formats, constraints, or parameter relationships.

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

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

States a specific verb ('restart'), a resource ('service'), and the scope ('all running containers'). The REST endpoint reinforces the exact operation, and it is clearly distinguishable from sibling tools like pause_service, resume_service, scale_service, and trigger_service_build.

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

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

No guidance is given on when to use this tool versus alternatives, and no prerequisites or exclusions are mentioned. The intended use is only implied by the verb 'restart'.

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

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

With destructiveHint=true already declaring mutation, the description adds useful behavioral context: the operation is MUTATING, it restores a paused service, and it can alter instance count and CI/CD/autoscaling state. The HTTP endpoint is also disclosed. It does not contradict annotations.

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

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

The description is compact and front-loaded with the critical MUTATING warning before the action. The endpoint string is useful and earned. The opening 'MUTATING:' is slightly redundant given the title and annotations, but the overall structure is clean and efficient.

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

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

For a mutation tool with full schema coverage and a destructiveHint annotation, the description is largely complete: it states the action, the optional restoration behavior, and the HTTP endpoint. It does not explain behavior when the service is not paused or describe the response, but those are not critical for invoking the tool correctly.

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

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

The input schema has 100% description coverage across all six parameters, so the schema already documents each field. The description only adds a high-level note that these settings are optional to restore, which is helpful but does not add detail beyond what the schema provides.

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

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

The description states a specific verb and resource: 'resume a paused service', and adds optional restoration of instance count and CI/CD/autoscaling state. This clearly distinguishes it from sibling tools like pause, restart, or scale by focusing on resuming a previously paused service.

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

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

The description establishes a clear condition: use this tool to resume a paused service, and optionally restore scaling/CI/CD/autoscaling state. It does not explicitly name alternatives or exclusions, but the 'paused service' condition gives enough contextual guidance for correct selection.

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

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

Annotations already declare destructiveHint=true and the title says 'mutates infra'; the description reinforces this with 'MUTATING:' and the POST endpoint. It does not add deeper behavioral context such as consequences of reducing replicas, scale-to-zero effects, or whether scaling is asynchronous, but the annotation covers the main safety signal.

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

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

The description is a single front-loaded sentence with the mutating nature, the exact operation, and the HTTP endpoint. Every element is useful and there is no filler.

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

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

For a simple three-parameter tool with all parameters documented and destructive behavior already annotated, the description provides the essential operation and endpoint. It could mention side effects of decreasing instances or scaling to zero, but the annotations and schema carry most of the required context.

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

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

Schema description coverage is 100%, and all three parameters are already fully described in the schema. The description only echoes projectId and serviceId in the endpoint path, adding no new semantic information about parameters.

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

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

The description states a specific verb and resource: 'set the number of running instances (replicas) for a service.' It also includes the exact endpoint, which distinguishes it clearly from sibling get/list tools and from pause, resume, and restart mutations.

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

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

The operation itself implies when to use it—when you need to change replica count—but there is no explicit guidance contrasting it with pause_service, resume_service, or restart_service. No when-not-to-use or alternative selection criteria are provided.

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

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

Annotations already declare destructiveHint=true, and the description reinforces it with 'MUTATING' while adding operational detail: the default build source, optional targets, and the exact POST endpoint. It does not contradict the annotations, and it provides enough side-effect context for an agent to know this is a mutating infra action.

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

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

The description is compact and front-loaded with the mutating nature and core purpose. The endpoint line is useful but somewhat redundant with the tool name/title, and 'MUTATING' repeats destructiveHint/title, so it is not perfectly waste-free.

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

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

For a 5-parameter mutation tool with destructiveHint and no output schema, the description covers the essential calling context: target resource type, default behavior, optional targeting, and HTTP verb/path. It does not describe response shape or prerequisites such as repository configuration, but those are adequately implied for this trigger operation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds a meaningful synthesis: an empty body means build the latest commit on the linked branch, and only branch, sha, or pullRequestId are used for targeting. This clarifies the relationship and default behavior beyond the individual parameter descriptions.

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

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

Description uses a specific verb+resource: 'start a new build for a build/combined service', which makes the operation unambiguous. It is clearly distinct from sibling tools such as list_service_builds, pause_service, restart_service, and scale_service, so an agent can select it without opening the schema.

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

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

The description frames the tool as MUTATING and explains the default call semantics: an empty body builds the latest commit on the linked branch, with optional alternatives for branch, SHA, or pull request. It gives clear context for when to use it, though it does not explicitly name exclusion conditions or alternative tools.

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