Scalingo MCP by usefulapi

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

Annotations already declare readOnlyHint=true, so safety is covered; the description usefully adds that the call requires an authenticated context, that it takes no targeting arguments, and roughly what comes back ('Returns { user }'). It stops short of documenting failure modes for expired/invalid tokens.

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

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

Three short clauses with zero filler: what it fetches and its fields, the exact API route, and the return envelope. The most useful information (scope and payload) is front-loaded.

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

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

With no output schema, the description compensates well by listing the returned fields and the response envelope, which is what an agent needs to plan downstream use. Only auth/error behavior is left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a no-param tool applies, and the description correctly signals no inputs are needed.

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 ('Fetch the authenticated user's account'), enumerates the returned fields, and gives the exact endpoint (GET /v1/users/self). This cleanly distinguishes it from the app-scoped siblings such as scalingo_get_app and scalingo_list_apps.

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

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

The phrase 'authenticated user's' implies the use case (resolving the caller's own identity), but there is no explicit when-to-use statement, no prerequisites, and no reference to alternatives. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /v1/apps/{app}) and the envelope shape ({ app }), which is genuine extra context, but says nothing about error behavior for missing apps or rate limits.

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

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

Three short clauses, zero filler, with the core purpose and returned fields front-loaded before the endpoint and return shape. Every sentence earns its place.

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

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

There is no output schema, and the description compensates by naming the returned fields and the { app } envelope, which is adequate for a single-read tool. It stops short of describing the field structure or failure modes, keeping it just shy of fully complete.

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

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

Schema description coverage is 100% and the sole parameter already documents that app accepts a name or an app id with an example. The description adds nothing about parameter semantics beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Fetch a single app's details') and enumerates the returned fields (region, stack, status, URLs, flags), which clearly separates it from list operations. It doesn't name a sibling such as scalingo_list_apps as the alternative, but the singular scope makes the distinction inferable.

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?

Usage is only implied: the agent can infer 'call this when you need details for one specific app', but the description never states when to prefer it over scalingo_list_apps, scalingo_get_app_stats, or scalingo_get_app_logs. No prerequisites or exclusions are given.

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

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

Beyond readOnlyHint=true, the description discloses the two-step flow, the dump-mode last-N-lines behavior, the exact return shape { logs_url, lines }, and the partial-failure case where only logs_url comes back. That failure-mode note is genuinely useful context an agent cannot get from annotations; rate limits or log retention are still unstated.

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

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

Three sentences, front-loaded with purpose, then mechanism and return shape, then the failure caveat. The inline API route is slightly more detail than an agent needs, but nothing is redundant or bloated.

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

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

There is no output schema, yet the description specifies the return object and the degraded return case, and the schema fully covers the two inputs. An agent has everything needed to call it and to interpret what comes back.

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

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

Schema coverage is 100%, so both `app` and `lines` are documented with bounds and defaults in the schema itself. The description only echoes 'last N lines' and adds no format or semantics beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Fetch recent application log lines', and explains the internal mechanism (authenticated logs_url then dump-mode download). The resource is distinct from siblings like scalingo_list_app_events or scalingo_get_app_stats, though no sibling is named explicitly.

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?

Usage is implied (recent log inspection for an app) and the fallback path is described, but there is no explicit statement of when to prefer this over scalingo_list_app_events or scalingo_request, and no exclusions or prerequisites are given.

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, so safety is covered. The description adds genuinely useful context beyond that: that the data is real-time (not cached/historical), the exact endpoint, and the return envelope { stats: [...] }, which tells the agent what to expect without an output schema.

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

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

Three short sentences: purpose first, endpoint second, return shape third. Every sentence carries information and there is no filler.

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

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

For a single-parameter read tool with no output schema, the description supplies the return envelope and the stat categories, which is sufficient to call it correctly. It stops short of describing individual stat fields or freshness semantics (e.g. polling behavior), which would make it fully complete.

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

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

Only one parameter exists and schema coverage is 100%, with the schema already explaining that 'app' accepts a name (my-production-app) or an id (app-…). The description adds nothing parameter-level, so the baseline 3 is appropriate.

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

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

States a specific verb (get real-time stats) and a precise resource (per-container CPU/memory/swap usage) for an app, and even names the underlying endpoint. It is clearly distinguishable from scalingo_list_containers in substance, but it never explicitly contrasts itself with that sibling.

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 'real-time' framing implies this is for live resource monitoring rather than inventory listing, but the description gives no explicit when-to-use, when-not-to-use, or alternative routing. Usage is left to inference.

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

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

Annotations only declare readOnlyHint=true; the description goes further by naming the concrete fields returned (status, git_ref, pusher, image size, timestamps) and the response envelope 'Returns { deployment }', which matters because there is no output schema. It does not cover failure behavior (e.g. not-found for an invalid deployment_id) or pagination, which are minor for a single-resource GET.

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

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

Three short, front-loaded sentences with no filler; the field list and return shape are the most useful parts and come first. The raw API path partly duplicates the parameters but is cheap and useful for agents mapping to Scalingo's REST API.

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 read tool, the definition covers what it returns, which resource it targets, and the underlying endpoint, while annotations carry the safety profile. Only failure modes and any caching/freshness behavior are unstated, which is a small gap 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%, with both app (name or app-… id) and deployment_id already documented in the schema. The description restates the path template GET /v1/apps/{app}/deployments/{deployment_id} but adds no new semantics such as id format or validity rules, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Fetch a single deployment's details') and enumerates the returned fields, so the agent knows exactly what it gets. 'Single' implicitly contrasts with the sibling scalingo_list_deployments, but the sibling is never named.

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?

Usage is only implied: 'a single deployment' suggests this is the detail lookup versus the list tool, and the required app + deployment_id make the precondition obvious. There is no explicit when-to-use/when-not guidance or named alternative, so the agent must infer the routing from the sibling list.

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, so safety is covered. The description adds genuine value beyond that: it discloses the polling nature, the GET endpoint, and the return shape with status values pending|running|done|error. It doesn't mention rate limits or polling cadence, so not a full 5.

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

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

Three front-loaded sentences with the purpose and triggering action stated first. The raw endpoint line is slightly redundant but earns its place by anchoring the request shape. Minimal waste overall.

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

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

There is no output schema, and the description compensates by stating the return shape ({ operation }) and the status enum. With annotations covering safety and both params documented, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and both params are already documented (app name/id, operation_id from Location header). The description maps them onto the URL path and repeats the Location-header origin of operation_id, adding only marginal meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (poll the status) and resource (asynchronous operation), and clarifies its role relative to sibling actions like scalingo_scale_app and scalingo_restart_app by noting those return an operation to track. An agent can distinguish it from the generic scalingo_request without opening the schema.

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

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

Explicitly says when to use it: after a scale or restart returns an operation to track. This provides clear context for invocation. No explicit exclusions or named-alternative comparison, which keeps it just below a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the underlying API route and the exact response envelope, including that each provider embeds its full plans array — important since no output schema exists and the payload is potentially large/nested.

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

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

Three compact sentences: purpose first, then endpoint, then return shape. No filler and nothing buried.

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

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

For a single-optional-param, read-only list call with no output schema, the description supplies everything needed to call it and interpret the result. Minor omissions: it doesn't say whether the response is paginated or how large the embedded plans list can get.

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

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

Schema coverage is 100% and the single optional category_id is already documented in the schema as a provider filter. The description mentions no parameters at all, so it adds nothing beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("List the addon providers available on Scalingo") and names the endpoint GET /v1/addon_providers, so the agent knows exactly what data comes back. It does not explicitly contrast with the neighboring scalingo_list_addons, which lists an app's provisioned addons rather than the catalog, leaving that distinction to be inferred.

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 parenthetical "databases, monitoring, etc." implies this is a catalog-browsing / pre-provisioning lookup, but there is no explicit statement of when to call this versus scalingo_list_addons or how the optional category filter changes the query. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds the underlying API endpoint (GET /v1/apps/{app}/addons) and the response envelope ({ addons: [...] }), which is meaningful since no output schema exists. Pagination or result-size behavior is not disclosed, keeping it short of a 5.

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

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

Three short sentences, zero filler, with the core purpose front-loaded before the API and return-shape details. Every sentence carries information an agent can use.

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 list tool the description covers purpose, scope, endpoint and return envelope, which is sufficient given annotations and full schema coverage. Only pagination/ordering behavior is absent.

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?

Single 'app' parameter with 100% schema description coverage that already explains name-or-id forms. The description adds no parameter-level semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the addons') plus a parenthetical scoping clarification ('databases, services') and 'provisioned on an app', which separates it from the sibling scalingo_list_addon_providers (available providers vs. actually provisioned addons). No ambiguity about what is returned.

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?

Usage is implied by the resource scope (needs an app and lists its addons), but there is no explicit guidance on when to prefer this over scalingo_request or scalingo_list_addon_providers. Nothing is misleading, but the agent must infer the 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?

With readOnlyHint already declaring a safe read, the description adds the underlying endpoint (GET /v1/apps/{app}/events), the pagination behavior, and the exact return shape. It doesn't mention rate limits, auth needs, or retention limits on older events, keeping it below the top band.

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

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

Three short sentences, front-loaded with what is listed and immediately followed by the endpoint and return shape. No filler or redundant restatement of the name.

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 paginated list with full schema coverage and no output schema, the description supplies the endpoint and response envelope, which is what an agent needs. It doesn't describe the shape of individual event entries, a minor remaining gap.

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

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

Schema description coverage is 100%, so the schema already fully documents app, from, page, and per_page. The description adds no parameter-specific meaning beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (app activity events) and enumerates event kinds (deployments, scaling, restarts, collaborator changes), which separates it from raw-log and deployment-specific siblings. It doesn't name any sibling explicitly, so it falls just short of the top band.

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 plus the 'from last N hours' and pagination cues give clear context for when this is the right call (audit/activity history over a time window). No exclusions or named alternatives (e.g. get_app_logs) are provided, so it stops at clear-context level.

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 value beyond that: it names the backing endpoint (GET /v1/apps), scopes results to the current region, and discloses the return envelope { apps: [...] }. It does not mention result limits or pagination behavior, which is the only meaningful gap for a list tool.

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

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

Three short sentences with zero filler, and the most important fact (what it lists and the access scope) is front-loaded before the endpoint and return-shape details.

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 parameterless read-only list tool this covers purpose, scope, and return shape adequately, and no output schema means the description's envelope hint matters. It stops short of explaining how the 'current region' is determined, which could matter given a scalingo_list_regions sibling exists.

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 tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. Crediting the region scoping note, which tells the agent filtering happens via ambient context rather than an input.

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

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

States a specific verb and resource ('List all Scalingo apps') plus a scope qualifier ('you can access in the current region') and the underlying endpoint. It implicitly contrasts with the singular scalingo_get_app, though it never names 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.

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

The phrase 'apps you can access in the current region' implies this is the discovery step before calling get_app or other per-app tools, but no explicit when-to-use, when-not-to-use, or named alternative is given.

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?

readOnlyHint=true already declares the safety profile, so the description's job is lighter. It still adds valuable disclosure: the response envelope { collaborators: [...] } and the fact that each entry carries a status, plus the underlying API endpoint for traceability. It does not cover permission requirements or error cases, keeping it below a 5.

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

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

Three compact sentences: purpose first, definition in parentheses, then API path and return shape. No filler and the key information is front-loaded.

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

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

For a single-parameter read tool with annotations covering safety, the description covers purpose, endpoint and return envelope, which is nearly everything an agent needs. Minor omissions are auth/error behavior and whether the list is ever paginated.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains that app accepts a name or app id. The description's API path template ({app}) corroborates this but adds no new syntax or format detail. 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?

A specific verb (list) and resource (an app's collaborators), with a parenthetical that defines what a collaborator is (users invited to the app) and what is returned alongside (their status). This is enough for an agent to distinguish it from sibling list tools such as scalingo_list_variables or scalingo_list_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 use case (fetch collaborators of a given app) is implied clearly, but there is no explicit when-to-use guidance, no prerequisite statements (e.g. app must exist, viewer permissions), and no named alternatives. Adequate but leaves routing to inference.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by naming the underlying API endpoint and specifying the returned shape, though it does not mention pagination, permissions, or error behavior.

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

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

The description is compact and front-loaded, immediately stating the resource being listed and then adding useful endpoint and return-shape details. Every sentence contributes relevant information without waste.

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 one-parameter read-only tool with full schema description coverage and a clear readOnlyHint, the description is complete enough. It compensates for the lack of an output schema by describing the return structure.

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 and fully documents the single app parameter. The tool description does not add semantics beyond that, which is acceptable given the high schema coverage but not exceptional.

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: listing an app's container formation, including process types, amounts, and sizes. It clarifies that this is the current scaling, but it does not explicitly differentiate itself from sibling tools such as scalingo_scale_app.

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?

Usage is implied by describing the tool as listing the current container formation/scaling, but there is no explicit guidance on when to use it versus alternatives like scalingo_scale_app or scalingo_get_app_stats. It provides enough context for an agent to infer it is an inspection tool, but not explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds real value beyond that by disclosing ordering (most recent first), pagination behavior, the underlying API endpoint, and the response envelope shape. It stops short of stating default per_page or total-count behavior in meta.

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

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

Three short sentences, zero filler, with the core behavior (list, most recent first, paginated) front-loaded before the endpoint and return-shape detail.

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

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

With no output schema, the description compensates by naming the return shape ({ deployments, meta.pagination }), which is the key missing piece. Minor gaps remain around default page size and whether meta carries a total count, but nothing essential to a correct call is absent.

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 app, page, and per_page are already documented with formats and bounds. The description only reinforces that results are paginated and hints at meta.pagination; it adds no syntax or default values 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?

States a specific verb and resource ("List an app's deployments") plus the ordering ("most recent first") and pagination, which cleanly separates it from the singular scalingo_get_deployment sibling. It never names that sibling explicitly, but the plural/ordering framing is enough to disambiguate.

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?

Usage is implied — you call this to enumerate all deployments of one app — but there is no explicit when-to-use versus scalingo_get_deployment (single deployment) or scalingo_trigger_deployment. The agent must infer the routing from the tool name.

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, so the safety profile is covered. The description adds value beyond that by naming the underlying endpoint and sketching the return envelope '{ domains: [...] }', which is genuinely useful since no output schema exists. Pagination and error behavior remain unstated.

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

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

Three short sentences, front-loaded with the purpose and followed by endpoint and return shape. The API path line is slightly redundant with the endpoint implied by purpose, but it earns its place by disambiguating scope.

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

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

For a single-parameter read tool with no output schema, the description is nearly complete: purpose, endpoint, and return shape are all present. It falls short only on pagination/ordering and what happens with an unknown app.

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

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

Schema coverage is 100% and the single 'app' parameter is documented with name-or-id format, so the schema does the heavy lifting. The description reinforces that the path is app-scoped but adds no new semantics such as accepted formats or validation rules; baseline 3 applies.

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

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

States a specific verb and resource ('List an app's custom domains') plus what the results carry ('TLS/canonical status'), so an agent knows exactly what comes back. There is no sibling tool operating on domains, so explicit differentiation isn't needed, but it also doesn't anchor itself against the broader list_* family.

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?

Usage is only implied: the required 'app' parameter signals it is a per-app query, and the description says it lists an app's domains. There is no statement of when to prefer this over, say, scalingo_get_app or scalingo_request, and no exclusions or prerequisites.

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

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

Annotations only declare readOnlyHint=true, and the description goes further: it names the endpoint and its auth host, which signals that credentials are required, and it discloses the account-scoped nature of the result. It doesn't cover pagination or caching, but for a small static-ish lookup that is a minor omission.

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

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

Three short sentences: purpose first, then the use case, then the API/return detail. Every sentence carries distinct information and nothing is repeated from the title or schema.

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

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

With no output schema, the description supplies the return shape ('{ regions: [...] }') and the per-region fields, plus the auth requirement. For a zero-parameter read tool, an agent has everything needed to call it and interpret the result.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing parameter guidance.

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

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

States a specific verb and resource ('List the Scalingo regions available to your account') and immediately adds what each item contains (API/dashboard/database hosts). No sibling tool overlaps, and the scope qualifier ('available to your account') tells the agent this is not a static global list.

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?

'Useful to discover the right SCALINGO_REGION' gives a concrete trigger for calling it. It doesn't name an alternative (e.g. scalingo_request for the same endpoint, or where SCALINGO_REGION is consumed), which keeps it from a 5.

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

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

Beyond readOnlyHint=true, the description discloses the trait that matters most: the response contains plaintext secret VALUES such as API keys and database URLs. It also documents the underlying API call and the exact response envelope, which annotations do not cover.

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

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

Three short sentences: purpose first, security warning second, contract third. Every sentence carries information an agent needs and nothing is padded.

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

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

No output schema exists, but the description supplies the return shape ({ variables: [{ id, name, value }] }), so the agent knows exactly what comes back. With one fully documented parameter and a declared read-only profile, nothing material is missing.

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

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

Schema description coverage is 100% and the single 'app' parameter already documents both accepted forms (name or app-… id). The description adds no additional parameter semantics beyond the schema, so the baseline applies.

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

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

States a specific verb (list) and resource (an app's environment variables), and pins the scope to a single app. It is unambiguously distinct from the mutating sibling scalingo_set_variables and from the app-detail siblings.

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

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

The secret-exposure warning gives real context for deciding whether to call this tool, effectively cautioning against casual use. It stops short of naming scalingo_set_variables as the alternative for modification, so no explicit when-not routing is 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 only declare readOnlyHint, so the description carries real extra weight: it states the hard constraint that only GET is permitted, that the path is relative to /v1, and that the default target is the regional API versus the auth host. It omits pagination, error, and rate-limit behavior, which matters for a raw pass-through tool, but the core behavioral envelope is disclosed.

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

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

Four tight clauses, front-loaded with the escape-hatch framing and the READ-ONLY constraint before the mechanical path/host details. No filler sentences.

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

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

No output schema exists, and the description implies the raw Scalingo API response is returned verbatim ('Scalingo API: GET {path}'), which is probably sufficient for a passthrough. What is missing is how non-2xx responses or paginated collections surface, which is the main residual gap for this tool.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning: a concrete path example beyond the schema's, and a list of the resource families that require on_auth_host. The query object is left to the schema, which is adequate since it is a free-form passthrough.

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

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

States a specific verb+resource (raw GET against any Scalingo API path) and frames it precisely as a power-user escape hatch for endpoints no dedicated tool wraps. An agent can immediately distinguish this from the 21 typed siblings such as get_app or list_regions.

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

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

Gives an explicit selection rule: use this only for paths 'not wrapped by a dedicated tool', which directly routes the agent to the typed siblings first. It also gives a sub-case routing rule (set on_auth_host for regions, scm_integrations, tokens) so the two host targets are distinguishable.

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 flag destructiveHint=true, but the description adds real value: it declares MUTATES, documents the 202 Accepted async response, and names the sibling tool for tracking the operation. That async/tracking disclosure is genuinely useful context beyond the annotation.

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

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

Four dense sentences, front-loaded with the MUTATES warning, then scope behavior, return semantics, and endpoint. No wasted 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 two-parameter mutation tool with no output schema, the description covers the safety signal, scope behavior, and the async return/tracking path. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema. The description's scope explanation largely restates the schema's 'omit to restart all' note, adding little new syntax or format detail.

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 (restarts) and resource (an app's containers) with a clear scope. It is easily distinguished from siblings like scalingo_scale_app and scalingo_trigger_deployment, which perform different 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?

Explains that scope optionally limits which process types restart, and omitting it restarts everything. It also points to scalingo_get_operation for tracking, giving clear usage context, though it doesn't explicitly contrast with alternatives like scale_app.

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

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

Annotations only supply destructiveHint=true; the description earns credit by disclosing the async 202 contract, the operation-tracking path, and the partial-application semantics. It does not warn that reducing amount (especially to 0) removes running containers — a material destructive consequence for a tool flagged destructive.

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

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

Three tight sentences, front-loaded with the mutation warning and effect, then partial-update rule, then return/endpoint mechanics. 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 two-parameter write tool with no output schema, the description covers effect, scope, and async return handling adequately. Minor gaps: what happens at amount 0, and any size/plan constraints, are left unstated.

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 app/containers/name/size/amount are all already documented in the schema; baseline is 3. The 'only included types are changed' sentence adds genuine meaning about how the containers array is interpreted (omission ≠ removal), but no additional per-field detail beyond that.

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: 'sets the container formation (number and/or size of each process type)'. The 'MUTATES' prefix and container-formation framing cleanly separate it from the read-only sibling scalingo_list_containers, and it names the exact API endpoint.

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 partial-update rule ('Only the container types you include are changed') tells the agent this is a targeted patch rather than a full replace, and it explicitly routes follow-up polling to scalingo_get_operation. It stops short of stating when NOT to use it (e.g., use scalingo_restart_app for restarts without resizing).

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 only destructiveHint=true in annotations, the description carries real weight: it discloses the restart side effect, the upsert behavior, the name/value size limits, the underlying API call, and the return shape. It stops short of saying whether variables omitted from the array are left intact or removed, which is the key unknown for a bulk PUT.

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 dense paragraph that front-loads the mutation warning, then side effects, limits, endpoint and return value in priority order. Only the repeated size limits are wasted words since the schema already covers them.

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 two-parameter mutation with no output schema, the definition covers safety signal, side effects, constraints and return shape ('Returns { variables }'). The main omission is whether the operation is additive or a full replacement of the app's variable set.

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 are already documented. The length limits restated in the description (≤64 name, ≤8192 value) duplicate the schema's own descriptions rather than adding semantics; 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 and resource: 'MUTATES Scalingo infrastructure — creates or updates environment variables in bulk.' That scope cleanly separates it from the read-only sibling scalingo_list_variables without either schema being opened.

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?

Upsert semantics ('created if new or updated if it exists') imply when this is the right call, and the bulk framing implies it replaces per-variable single writes. However, it never names scalingo_list_variables as the read path or states any exclusion, so the agent must infer the boundary.

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 the write nature ('MUTATES') while adding value beyond the annotation: the concrete REST endpoint (POST /v1/apps/{app}/deployments), the return shape ({ deployment }), and the absence of a dedicated rollback endpoint. It stops short of disclosing permissions required, whether the call is asynchronous/long-running, or rate limits.

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?

Roughly four short clauses, front-loaded with the mutation warning, then input format, then operational caveat, then endpoint/return. No filler and every element is actionable.

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

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

With no output schema, the description usefully states the return payload and the endpoint, and covers the archive-URL requirement plus rollback semantics. What remains missing for a mutating deployment tool is whether the call returns immediately vs. blocks on a build, and any permission prerequisites.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: source_url must be a tar.gz reachable by Scalingo, and git_ref is framed as the handle you re-deploy to roll back. That goes beyond the schema's label-only wording.

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

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

States a specific verb and resource — 'triggers a new deployment from a source archive URL' — and immediately scopes the input (tar.gz reachable by Scalingo). An agent can distinguish it from scalingo_list_deployments, scalingo_get_deployment, and even from mutation siblings like scalingo_restart_app or scalingo_scale_app because the deployment source is named.

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

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

Gives explicit task context (create a deployment from an archive) and an important alternative path: rollback is achieved by re-deploying a previous git_ref/archive since no rollback endpoint exists. It does not explicitly compare against scalingo_restart_app, which is the nearest mutation sibling an agent might confuse this with.

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