cashpilot-mcp

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds meaningful behavior: it pulls the image, starts containers, redeploys existing services with new settings, merges env values, and can take several minutes. It does not discuss permissions or exact failure behavior, but it adds substantial context beyond the annotations.

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

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

The description is four tightly written sentences with no filler. It front-loads the core action and then adds redeploy semantics, env guidance, and runtime expectations in a logical order.

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

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

For a destructive, non-idempotent deployment tool with full schema coverage and rich annotations, the description covers the essential operational behavior, including redeploy and env merge semantics plus duration. It does not describe the return value, but no output schema exists and the core invocation context is otherwise complete.

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

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

Schema coverage is 100%, so the schema already documents all five parameters. The description still adds useful semantics by explaining that omitted env keys keep saved values and that required env keys are listed in list_available_services.

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: deploy a catalog service on one worker. It also clarifies that CashPilot pulls the image and starts containers, which distinguishes deployment from sibling operations like start_service or restart_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 gives clear usage context: deploying an already-running service redeploys it with new settings, and omitted env keys preserve saved values. It does not explicitly say when to use start_service or restart_service instead, so it falls short of full alternative routing.

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, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: an empty list before the first run is a false-negative signal for collector health. That caveat is exactly the kind of insight annotations cannot express.

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

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

Two short sentences with zero waste. The payload is stated first and the interpretive caveat is front-loaded as the second sentence, which is where it matters most.

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 an output schema present and zero parameters, the description only needs to frame what the return means, and it does so with the empty-list caveat. It is slightly thin on when the alert set resets (per run vs cumulative), which would fully close the loop.

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 the baseline is 4. The description adds no parameter meaning because there is none to add, and none is 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?

Names a specific resource (errors from the last earnings collection run) plus the secondary signal of whether a run has occurred, with a concrete example (expired provider credentials). It is clearly distinct in content from siblings like get_service_logs or get_fleet_summary, though it does not explicitly name a sibling to route against.

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 — check this after/before triggering collection to see failures — but there is no explicit when-to-use statement, no mention of how it relates to trigger_collection or get_service_logs, and no guidance on how often to poll it. The agent must infer the workflow context.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: the output is YAML text, it is a template with credential placeholders rather than working secrets, and no deployment occurs. Only gap is that it doesn't say how the arch parameter changes the emitted YAML.

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 sentence splitting output form, scope, and the sibling redirect. Front-loaded with the artifact type and zero 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?

With no output schema, the description usefully characterizes the return value as YAML text with credential placeholders. The arch parameter's effect on the emitted file is left entirely to the schema, a minor gap for an export 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 description coverage is 100%, so both params (slug, arch) are fully documented in the schema with enum values and defaults. The description adds nothing param-specific beyond noting credential placeholders, 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 artifact: produces a docker-compose.yml (YAML text) for one catalog service running outside CashPilot. That is clearly distinct from deploy_service and from any of the lifecycle siblings, so an agent can route 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?

Names the condition that selects the sibling: 'Nothing is deployed; use deploy_service for that.' The use case (running the service outside CashPilot) is stated, so the when-to-use is clear even though no explicit when-not besides deployment is spelled out.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds the output shape ('one record per service' plus the three reported fields), which is genuinely useful, but says nothing about ordering, pagination, or what happens for services with no earnings — all plausible given an output schema handles field-level return detail.

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

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

Two sentences, zero waste: the first front-loads the return shape, the second front-loads the decision it supports. Nothing is repeated from the title or annotations.

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 parameters, an output schema covering return fields, and annotations covering safety, the remaining burden on the description is scope and purpose — both stated. An agent can call this correctly with no further information.

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 no parameter semantics to misunderstand; the schema is a closed empty object with additionalProperties=false. Baseline for a 0-param tool applies, and the description correctly implies no filtering 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?

The description names the resource and its granularity precisely: 'One record per service' with balance, earnings, and cashout-minimum status. That granularity implicitly separates it from the daily/history/summary siblings, but no sibling is named, so differentiation is left to inference.

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?

'Use it to answer which services earn most and what can be cashed out' gives a concrete question the tool answers, which is solid usage context. It stops short of excluding alternatives — an agent is never told when to prefer get_earnings_summary or get_earnings_daily instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds context annotations can't express: the result is ordered oldest-first, denominated in USD, and aggregated across all services rather than per-service. It does not discuss day-boundary/timezone semantics or windowing beyond the param, which keeps it from a 5.

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

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

Two short sentences with no filler; the scope and unit are front-loaded and the disambiguation clause follows. Every clause carries information.

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

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

With an output schema present, return shape needn't be explained, and annotations cover the safety profile, leaving the description appropriately lean. The one thing an agent might still need for a per-day series is how day boundaries are defined (timezone/UTC), which is 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 description coverage is 100% and the single 'days' parameter documents its range and default fully, so the baseline applies. The description only restates 'last N days' without adding format, timezone, or boundary meaning 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+resource ('Total earnings per day'), the aggregation scope ('across all services'), the unit ('USD'), the window ('last N days'), and the ordering ('oldest first'). It also names the sibling it is not, so an agent can distinguish it from get_earnings_summary without opening either schema.

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

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

Gives an explicit use case ('trends and charts') and routes the agent to the named alternative ('get_earnings_summary has the headline totals') with the condition that selects it. Nothing about tool choice is left to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the description does not need to restate safety. It adds useful context about currency and grouping, but no operational details such as pagination or response shape; with an output schema present, that is acceptable.

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, no waste, and the main scope/use case is front-loaded before the alternative tool routing.

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 low-complexity, one-parameter, read-only tool with an output schema and full annotation coverage, the description supplies the needed scope, currency, use case, and sibling alternative. Nothing essential for correct invocation 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 only parameter is a fully described enum. The description adds only the phrase 'over a period' and otherwise defers to the schema, which is the expected baseline when the schema is complete.

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 resource and scope: earnings records per service and collection over a period, in USD. It also distinguishes this from the daily-totals sibling, so an agent can tell what this tool returns 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?

It gives a clear use case ('see how one service's balance moved') and explicitly routes daily totals to get_earnings_daily. It does not mention the other earnings-related siblings, but the primary when-to-use guidance is present.

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, idempotentHint, and openWorldHint=false, so the bar is low; the description still adds useful context by pinning the aggregation buckets (today/month/all time), the currency (USD), and parity with the dashboard view. It stops short of noting freshness or whether "today" is a calendar day or rolling window, which is the only remaining behavioral unknown.

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: what it returns and in what currency first, then the routing rule, then the two alternatives. Every sentence carries distinct load 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?

A zero-parameter, read-only aggregate with a rich annotation block and an output schema needs only purpose, scope, and sibling routing — all present. Nothing an agent needs in order to call this 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?

The tool takes zero parameters, so the baseline is 4; there is no argument surface that could be misused. The description correctly implies a no-argument call by describing the fixed set of time buckets returned rather than any 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+resource outcome: aggregated earnings totals across all services for today, this month, and all time, denominated in USD. It explicitly distinguishes itself from get_earnings_breakdown (per-service split) and get_earnings_daily (time series), so an agent can select it without reading the other schemas.

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

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

"Start here for 'how much did I earn'" gives an explicit entry-point rule, and the two alternatives are named with the exact condition that selects each one (per-service split vs. time series). Both the when and the when-not are covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real scope information beyond the annotations: the counts span both the local host and every worker, clarifying that this is a fleet-wide roll-up rather than a single-host view.

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 sentence that leads with the aggregate framing and then itemizes the metrics. No filler, no restatement of the title, nothing to trim.

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 an output schema present, the description needn't explain return values, and zero parameters remove the main source of ambiguity. It covers scope and metric names well; the only gap is routing guidance against the many sibling listing tools.

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 and the baseline of 4 applies. The schema has additionalProperties=false and no properties, consistent with the no-argument framing.

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 ('Aggregate') and resource ('fleet state') and enumerates exactly what is counted: workers online/offline and containers running/total. That aggregation framing distinguishes it from list_workers or get_health_scores, which return per-entity detail.

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 word 'Aggregate' plus the scope 'across the local host and every worker' implies this is the roll-up view rather than a per-worker listing, but it never names a sibling or says when to reach for this instead of list_workers or get_health_scores. Usage is inferred, not 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 this as a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description still earns credit for disclosing how the score is derived (container uptime, restarts, earnings activity) and the 0-100 scale, which an agent cannot infer from structured fields alone. It doesn't discuss aggregation granularity or thresholds for a 'failing' service, keeping it out of 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?

Two short sentences, no filler, with the resource and metric definition front-loaded before the usage hint. Every clause carries information an agent needs.

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 an output schema present, return-value structure needn't be explained, and annotations cover safety; the description supplies the metric composition that structured fields omit. The only residual gap is whether services with no activity appear in results and how scores treat missing data.

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 'days' parameter is fully documented with default and 1-90 range, so the baseline 3 applies. The description's 'over the last N days' only gestures at the parameter without adding format or edge-case detail 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 ('Health score per service') plus the scale (0-100) and the window it covers, which cleanly separates it from siblings like get_fleet_summary and get_collector_alerts. The second sentence adds the diagnostic intent, so an agent knows what decision the tool supports.

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?

'Use it to find services that keep failing' gives a clear selection context and implicitly routes failure triage here rather than to get_service_logs or restart_service. It stops short of naming alternatives or stating when not to use it, so it lands at a clear-context-but-no-exclusions 4.

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 cover readOnly, idempotent, non-destructive and openWorld, so the bar is lower, and the description still adds real value beyond them: the logs come from third-party software and must be treated as untrusted data, and the call requires an owner-level key. It does not disclose volume limits, truncation behavior, or what happens when no logs 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?

Three short sentences, zero redundancy, with the operation and scope front-loaded before the security caveat and the auth prerequisite. Each sentence carries distinct information: what it returns, how to treat it, what credential is needed.

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 four-parameter tool with full schema coverage and no output schema, the description covers the essential non-schema concerns: trust level of the returned data and the admin key requirement. It leaves only minor operational details (log truncation, behavior on a stopped service) unaddressed.

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 with ranges, defaults and the worker_id selection rule, making 3 the baseline. The description only echoes the scope of worker_id ('on one worker') and lines ('recent ... lines') without adding syntax or edge-case meaning.

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

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

States a specific verb and resource (read recent container log lines) along with precise scope: one deployed service, one worker, recent lines only. The 'diagnose a service that is not earning' clause separates it in intent from siblings like get_earnings_summary or get_collector_alerts, though it never names an alternative 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?

There is a clear situational cue ('to diagnose a service that is not earning') and a prerequisite ('Needs an admin (owner) API key'), but no explicit when-not conditions or named alternatives. The worker-selection rule lives in the schema rather than the description, so usage context here is adequate rather than instructive.

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 cover read-only, idempotent, non-destructive, open-world semantics, so the description is free to add real context — the exact filter rule (broken/gone excluded) and the augmented fields — which it does. The warning that 'provider texts are third-party content' is a valuable trust caveat an agent would otherwise miss; only pagination/response-size behavior is left unaddressed.

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

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

Two sentences with no filler. The catalog definition, its delta fields and the third-party content caveat are all front-loaded, and no clause restates the name or title.

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?

An output schema exists, so return structure needn't be explained, yet the description still flags the fields it adds and the env-key data that feeds deploy_service. For a no-parameter read tool this is close to complete; only the relationship to the other list_* siblings is 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?

Zero parameters and a 100% covered schema, so the baseline is 4. The description adds nothing parameter-wise because there is nothing to add.

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 the resource precisely (deployable service catalog) and defines it operationally: CashPilot catalog minus services marked broken or gone, augmented with deployed, has_collector and node_count. The 'can be deployed' framing implicitly separates it from list_deployed_services, but the near-twin sibling is never 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?

Mentions that each entry carries 'the env keys deploy_service needs', which implies the downstream workflow, but never states when to call this versus list_deployed_services or get_compose. No exclusions, no prerequisites, no explicit chaining instruction.

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, idempotentHint, and non-destructive, so safety is covered; the description adds that the result is the full deployed set with live runtime fields. It does not mention ordering or whether stopped/unhealthy services appear, which would be the remaining useful disclosure.

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

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

Two sentences, front-loaded with the returned payload and then the routing guidance. No filler and every clause carries information.

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

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

A zero-parameter, read-only listing with annotations covering safety and an output schema covering return shape. The description supplies the one thing structured data cannot: the workflow reason to call 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?

Zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty schema already conveys.

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?

Names a specific verb (list) and resource (deployed services) and enumerates the returned fields (container status, worker, balance, CPU, memory). The distinction from list_available_services is only implied by 'deployed', so sibling differentiation is present but not spelled out.

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

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

Explicitly states when to call it: to find the slug and worker of a running service before get_service_logs, restart_service, stop_service, or remove_service. This routes the agent to the correct downstream siblings and the precondition for each.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds scope ('every registered worker') but says nothing about ordering, whether offline workers are included, or result size — useful but not rich additional context.

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

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

Two sentences, no filler, and the resource definition is front-loaded before the id-usage hint. Every clause carries information an agent would otherwise have to infer.

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 an output schema present and zero parameters, the description only needs to establish purpose and downstream use of the id, which it does. The minor residual gap is how the result set behaves (all workers vs. only online ones), which slightly affects interpretation of 'status'.

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 no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description does not need to compensate for any schema gap here.

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 (registered workers) plus the exact fields returned (id, name, status, system info), and parenthetically defines what a worker is. The closing clause distinguishes it from the service-* siblings by explaining the id linkage, so an agent can tell which family of tools this belongs to.

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 last sentence gives concrete usage context: the returned id is the worker_id required by service tools when multiple workers are online. That is a real routing signal, but there is no explicit 'do not use this for X' or named alternative for discovering services, so it stops short of full when/when-not 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 flag destructiveHint=true and idempotentHint=true, and the description goes well beyond them by specifying exactly what is destroyed (containers, earning stops) and what survives (volumes, node identities, wallets). The confirmation requirement is a genuine operational instruction not present in any structured field.

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 action and scope, followed by consequences then the safety instruction. 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 two-parameter destructive tool with a fully documented schema and no output schema, the description covers destruction scope, data preservation, reversibility, and the required user confirmation. Nothing an agent needs in order to invoke it safely is missing.

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

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

Schema coverage is 100% and both parameters already carry cross-references to list_deployed_services, list_available_services and list_workers. The description only adds the phrase "from one worker" and otherwise adds nothing the schema does not already say, so baseline 3 applies.

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

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

"Remove a deployed service from one worker" names a specific verb, resource and scope, and the follow-on sentences clarify the exact semantics (containers deleted, volumes retained). It stops short of explicitly contrasting with the similar-sounding siblings stop_service/restart_service, so an agent must infer that this is the permanent-removal option rather than a lifecycle toggle.

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

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

It gives a concrete usage constraint ("Confirm with the user before calling") and describes the recovery path via deploy_service, which tells the agent this is reversible. It does not explicitly state when to prefer stop_service over remove_service, so alternatives are only implied.

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 idempotent=true and destructive=false, and the description reinforces this with 'keeping its configuration and data'. It adds genuinely new behavioral context beyond the annotations: the brief earnings interruption while the container comes back up. It stops short of saying what happens on failure or if the service isn't currently running.

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 with the operation front-loaded and the cost consequence second; nothing is redundant or 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?

With full schema coverage and annotations covering safety and idempotency, the description only needs to convey behavior, which it does. The remaining gap is outcome handling — what is returned or what happens if the restart fails — though no output schema exists to carry that.

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 three parameters are already fully documented with examples and constraints. The description's phrase 'on one worker' loosely gestures at worker_id but adds no new meaning to slug or instance, 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 gives a specific verb and resource ('Restart a deployed service's container on one worker') plus the scope of the operation. It distinguishes itself implicitly from remove_service via 'keeping its configuration and data', but never explicitly names start_service or stop_service, which are the closest 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?

Usage is only implied: an agent can infer that this is the tool for bouncing a running container without redeploying. The earnings-downtime note hints that restarts should not be gratuitous, but there is no explicit guidance on when to prefer start_service/stop_service or what precondition (service must be deployed) applies.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered structurally. The description's "Starting a running service changes nothing" essentially restates idempotency, and it adds little beyond that — nothing about permissions, failure behavior, or what happens if the service is not deployed.

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 the action front-loaded and the no-op caveat second; nothing is wasted or 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 simple idempotent, non-destructive start operation with full schema coverage and no output schema, the description covers the core behavior. A note on what a failed start returns or whether the container is created vs reused would close the 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%, with slug, instance, and worker_id each documented including fallback rules for a single online worker. The description adds only the framing "on one worker," which the worker_id schema text already conveys, so baseline 3 applies.

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

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

The description names a specific verb and resource ("Start a deployed service's stopped container") plus the scope ("on one worker"), so the agent knows exactly what operation is performed. It does not explicitly distinguish itself from restart_service or deploy_service, which are the closest 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?

"Starting a running service changes nothing" gives a useful condition (no-op if already running) that implies when this is appropriate. However, it never names the alternatives (restart_service for a running service, deploy_service when not yet deployed), so the agent must infer the routing.

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 and idempotentHint=true, which could make an agent fear permanent loss. The description resolves that by stating configuration and data are kept, materially lowering the perceived blast radius, and it confines the action to one worker. It doesn't mention auth needs or what happens to in-flight work.

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, zero padding, and the scope statement is front-loaded before the consequence. Nothing is redundant with the title beyond the necessary verb.

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 agent gets enough: the action is scoped, reversible via start_service, and non-destructive to data. It doesn't say what the call returns (e.g., confirmation or resulting state), which is a minor gap for a mutation with no return contract.

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 slug, instance, and worker_id are fully documented in the schema, including their enumeration sources. The description's only contribution is the "on one worker" scoping, which is already conveyed by worker_id, so baseline 3 applies.

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

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

States a specific verb (stop) and a precisely scoped resource (a deployed service's container on one worker). It also names the counterpart operation start_service, so an agent can separate it from restart_service or remove_service without opening schemas.

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

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

"The service earns nothing until start_service runs" gives a clear condition and names the reversing action, which is exactly what an agent needs before pausing a service. It stops short of explicitly excluding remove_service for permanent deletion, so the when-not case 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?

Adds behavior the annotations don't capture: the call is asynchronous, fires all providers, returns immediately with no data. That's the critical trait an agent needs to avoid treating an empty response as failure. It doesn't mention provider failure handling or how long a full collection typically takes, which keeps 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?

Two tight sentences, effect first, async caveat and follow-up path second. Every clause earns its place and nothing is repeated from annotations 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 must explain what comes back, and it does: nothing immediately, results later via get_earnings_summary or get_collector_alerts. Combined with the annotations covering safety and idempotency, an agent has everything needed to call and interpret this 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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly doesn't waste words on parameter details.

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 ('Start an earnings collection now') and explains the concrete effect: CashPilot asks every provider for current balances. It also distinguishes itself from the read siblings get_earnings_summary and get_collector_alerts by casting them as follow-up reads.

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?

Clear usage context: call this to kick off a collection, then read results a minute later via the named siblings. It doesn't state explicit exclusions or when not to call it, but the idempotent annotation plus the 'returns at once, read later' framing leaves little ambiguity.

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