Flux Cloud

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond the annotations: public ports are auto-picked, data replication is enabled by default, and the response includes local validation errors and warnings. That said, it omits anything about the private-key inputs (fluxIdPrivateKey/paymentPrivateKey) and any auth or side-effect notes.

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, front-loaded with what the tool produces and followed by the behavioral defaults and return content. Nothing is wasted, though the second sentence could be slightly more informative about the returned validation output.

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

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

For a 13-parameter builder with 54% schema coverage and no output schema, the description covers the overall purpose, the notable defaults, and the return shape (spec + errors/warnings). It does not address the numerous undocumented parameters or the sensitive private-key inputs, leaving meaningful gaps for a tool of this complexity.

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

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

Schema description coverage is only 54%, so the description should compensate but largely does not. It gestures at the key input groups ('images, ports, resources and a term') and confirms auto-picking of public ports and the replication default, but many parameters (owner, nodes, geolocation, contacts, expireBlocks, private keys) get no added meaning. Baseline 3 fits given partial schema coverage and partial description help.

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 concrete verb+resource: 'Turns images, ports, resources and a term into a complete, correctly formatted v8 specification.' This is specific and clearly a build/assembly operation. However, it does not differentiate itself from close siblings such as flux_validate_spec or flux_quote_app, which an agent could easily confuse it with.

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 no explicit when-to-use or when-not-to-use guidance. The agent is left to infer that this belongs before validate/deploy, and the description never mentions the sibling tools that share its domain (validate_spec, quote_app, deploy_app). No prerequisites or ordering are 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 destructiveHint=true, openWorldHint=true, and non-idempotency. The description goes further by explaining what destruction means (the app expires within ~an hour and the network uninstalls it everywhere) and that confirm=true signs and pays a usually minimal update fee while false returns only the plan. That is real added behavioral 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?

Three tight sentences: purpose and mechanism first, then the confirm behavior. Every sentence carries information and nothing is repeated from the schema 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?

For a destructive, no-output-schema tool this covers the essentials: what happens to the app, the timing, the cost implication, and the preview/execute switch. It stops short of noting reversibility (can a cancelled app be restored?) or any caveats about the 'name' argument, but the picture is largely 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 only 50%, but the description carries the most important non-obvious parameter: confirm=true signs/pays versus false which returns the plan. The two private-key parameters are documented in the schema itself, and 'name' is self-evident from the tool context, so the description largely compensates for the coverage gap.

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 ('Ends an app early') and explains the underlying mechanism (term update to expire within an hour, then network-wide uninstall). This clearly separates it from deploy/build/list siblings, though it never names the closest alternatives such as flux_control_app or flux_quote_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?

The confirm=true/false split implies a preview-then-execute workflow, which is useful usage guidance. However, there is no explicit statement of when to choose this over flux_control_app (stop/start) or flux_quote_app, and 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description adds real context on top: hard=true wipes app data, remove is non-terminal because the registration persists and the app re-spawns elsewhere, and the owner key is required. This is exactly the behavioral detail an agent needs for a destructive multi-action 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?

Dense but every clause carries distinct decision-relevant information, front-loaded by action name so the agent can stop reading once it finds its action. No filler or restatement of the 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?

For a destructive, key-requiring multi-action tool with no output schema, the description covers actions, scope, data-loss conditions and key needs. The only shortfall is that it doesn't indicate what the call returns or how long a redeploy/remove takes to settle, which would help an agent decide whether to poll.

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?

With schema coverage at 57%, the description compensates well by explaining the semantics of action (three values), hard (wipes data), scope (node vs global) and nodeIp's dual role. It does not mention paymentPrivateKey or clarify the owner-key parameter's exact mapping, leaving a small gap against the remaining undocumented schema entries.

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 concrete resource (app containers/instances) and enumerates each verb with its distinct effect: restart restarts containers, redeploy re-pulls and recreates, remove uninstalls from nodes. It even distinguishes itself from the sibling flux_cancel_app, so an agent can route correctly without opening the 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?

Explicit when-to-use guidance per action, plus a clear when-not/alternative: remove leaves the registration so the network re-spawns it, therefore use flux_cancel_app to actually stop paying. Scope selection (node vs global) is also spelled out, which is the key decision an agent must make.

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 flag destructive/non-idempotent/open-world, and the description adds substantial context beyond them: payment is drawn from the payment address, signing uses the Flux ID, and the no-confirm path is a safe dry run that spends nothing. This exposes the two-phase commit and spend behavior an agent must reason about.

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 compact sentences, front-loaded with the confirm/no-confirm decision, then the register-vs-update scope, then the follow-up call. Every sentence carries distinct load.

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 5-param tool with nested objects and no output schema, the description covers the mutation path, the safe preview path, identity/payment keys, and the returned txid handoff. 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 coverage is high (80%), so the schema already documents spec, confirm, keys, and enterprise. The description reinforces confirm and the payment-address semantics without adding syntax beyond the schema, so it sits just above the baseline for high-coverage schemas.

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 specific verbs and resource: validates, quotes, signs, broadcasts, pays for an app. Explicitly covers both 'register a new name' and 'update an existing app of the same owner', distinguishing it from siblings like flux_validate_spec and flux_quote_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?

Gives the key conditional: with confirm=true it signs/broadcasts/pays, without confirm it only returns the plan and spends nothing. Also names the follow-up tool (flux_wait_for_app) and the txid to pass. This is explicit when-to-use and what-happens-next 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?

Discloses that secrets are returned, that nothing is stored or sent elsewhere, and how to persist them. This adds significant value beyond the readOnlyHint and openWorldHint annotations.

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

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

Three tight sentences: what it creates, what to do with the result, and the security guarantee. Front-loaded and 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?

Given no output schema, the description explains the return (secrets) and required post-actions, and it covers security behavior. It is complete for a key-generation 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?

The schema covers parameters at 100% and describes them well, but the description reinforces intended use (dedicated key, fund only what you intend to spend) and the schema actually resembles the output rather than input—still, the description clarifies the output secrets.

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

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

States a specific action: creates two fresh WIF private keys, one for Flux ID and one for payment address. This clearly distinguishes it from siblings like flux_get_identity or flux_deploy_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?

Explains the post-generation workflow (store in environment variables, restart server) but does not explicitly contrast with alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description goes beyond that by disclosing an active probing step (shared domain HTTP, per-instance TCP and HTTP), interpreting a 503, and noting it is expected for non-web apps — genuinely useful behavioral context an agent could not get from 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?

A single front-loaded sentence that leads with the core action and enumerates the return contents; the probing and 503 detail are appended efficiently. It is dense but not 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 no output schema, the description compensates by listing the returned fields and explaining the reachability payload, which is what an agent needs to interpret results. It omits any mention of the key-related parameters, but those are handled in the schema.

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 75%, so most parameters are already documented (ports for private apps, the two private keys). The description adds no parameter-level detail beyond the schema, 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 (looks up) and resource (any app on the network by name) plus the exact payload returned: spec, expiry, instances, URLs, and a reachability check. This clearly separates it from siblings like flux_get_app_logs, flux_get_app_stats, and flux_list_my_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 'any app on the network by name' implies the lookup context, and the 503 explanation hints at diagnostic use, but there is no explicit when-to-use versus flux_get_app_stats or flux_list_my_apps, and no stated prerequisites. 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 already establish readOnlyHint=true / openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the owner-key requirement, that private apps are decrypted with that key, and that single-component apps auto-select while multi-component apps return the available names. It does not mention whether the payment key is required for this call, which is the one behavioral gap.

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 core action, and every clause carries information (scope, prerequisite, fallback behavior). No filler or restatement of the 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?

For a 6-parameter read-only tool with no output schema, the description covers the essentials an agent needs: what it returns (log lines), the auth requirement, and component resolution. It omits whether a payment key is consumed and any hint about output ordering or truncation, which leaves a small but real 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 coverage is 67%, and the description genuinely adds meaning: "last N lines" clarifies the semantics/cap of the `lines` integer, "one of the nodes running it" maps to nodeIp, and the auto-pick/listing sentence explains `component` behavior not captured in the schema. It adds little on the two key parameters beyond what their schema descriptions already say.

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?

"Fetches the last N log lines of an app" gives a specific verb and resource, and "from one of the nodes running it" scopes it precisely. It is obviously distinct from flux_get_app / flux_get_app_stats, but it never explicitly contrasts itself with any sibling, so it stops short of a 5.

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

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

It states a prerequisite ("Requires the owner key") and describes the conditional component-selection path, which implies how to invoke it correctly. However, there is no guidance on when to choose this over other inspection tools (flux_get_app, flux_get_app_stats) and no stated exclusions.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds the owner-key auth requirement plus the single-node scoping. It does not say whether stats are sampled live or cached, what granularity/window they cover, or any rate limit, leaving meaningful behavioral gaps for a monitoring call.

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 resource front-loaded and the auth requirement trailing; nothing is wasted. It is efficient, though bordering on under-specified rather than richly concise.

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 readOnly/openWorld annotations and no output schema, the safety profile is covered, but the description does not say what the returned stats contain (per-container? aggregates? units?) or how node/component interact, which an agent needs to interpret results for a 5-parameter 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 60%, so the schema documents the two private keys itself. The description contributes 'on one node' (implying nodeIp) and 'owner key' (implying fluxIdPrivateKey), but says nothing about 'component' for multi-component apps or how nodeIp defaults when omitted.

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: live CPU, memory and network stats for the containers of an app on one node. This is distinguishable from flux_get_app (metadata) and flux_get_app_logs (logs) by the 'stats' resource, 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?

There is no explicit when-to-use, no condition selecting this over flux_get_app or flux_get_app_logs, and no exclusion. 'Requires the owner key' is an auth prerequisite rather than usage guidance, so the agent must infer the monitoring/metering 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 readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the explicit security guarantee 'Never returns private keys' and the diagnostic behavior 'Explains what to configure if keys are missing'. It stops short of describing rate limits or failure modes, so 4 rather than 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, each earning its place: what is returned, the diagnostic behavior, and the security guarantee. The primary payload (returned values) 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?

There is no output schema, so the description carries the burden of describing return values and does so completely (ID, payment address, balance, USD value). Combined with annotations covering the read-only/open-world profile and a fully documented schema, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and both parameters (fluxIdPrivateKey, paymentPrivateKey) are fully documented in the schema, including guidance to use dedicated keys. The description adds only the vague 'if keys are missing' condition and no syntax or format detail, 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 ('Returns') and enumerates the exact resources: Flux ID (app owner address), payment address, spendable FLUX balance and its USD value. It is unambiguous about what the tool produces, though it never names or contrasts a sibling tool, so the 4 rather than 5.

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 what to configure if keys are missing' implies a usage context (diagnosing missing/unconfigured keys), which is a useful hint. However, there is no explicit when-to-use statement, no prerequisites, and no alternatives such as flux_generate_keys or flux_get_network_info, so guidance is 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful return-content context, but it is silent on the surprising fact that a read-only network query accepts two WIF private keys (both optional) and what they are used for — a genuine behavioral gap the schema does not explain.

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 front-loaded sentence listing the four returned data points with no waste. It is a fragment rather than a sentence, but nothing needs trimming.

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, so the description correctly carries the burden of naming the returned fields, and it does so completely. Only the unexplained private-key requirements for a read-only call keep it from being fully self-sufficient.

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 key parameters are already documented in the schema with their own caveats. The description adds nothing about them, 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 enumerates exactly what is returned (node counts by tier, block height, FLUX/USD rate, payment address), so the agent knows the resource and payload even though the phrasing is a noun list rather than a verb phrase. The name 'flux_get_network_info' supplies the verb, and the content is plainly distinct from the app-deployment 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?

There is no statement of when to use this tool, no prerequisites, and no mention of alternatives among the fourteen siblings. The agent must infer usage from the returned-data list alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. Because there is no output schema, the description's enumeration of returned data (rate card, live rate, discount, reference-size estimates) adds real behavioral value beyond annotations, though it says nothing about freshness/rate limits or why two private keys are accepted by a read-only call.

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, with the payload contents front-loaded and the sibling routing placed immediately after. Every clause earns its place.

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

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

With no output schema, the description correctly takes on the burden of describing return values, and it does so concretely. Safety is covered by annotations and credential usage is covered by the schema, so an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100% and both parameters carry detailed guidance in the schema, so the baseline is 3. The description adds no parameter-level meaning at all, notably not explaining why a read-only pricing call needs fluxIdPrivateKey and paymentPrivateKey.

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+resource ('Returns the current USD rate card') and enumerates exactly what is included: live FLUX/USD rate, pay-in-FLUX discount, and instant USD estimates. It also explicitly separates itself from the sibling flux_quote_app, so an agent can pick between them without opening a 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?

States the alternative tool by name and the condition that selects it ('Use flux_quote_app for the exact price of a specific app'). This is an explicit when-to-use-this vs when-to-use-the-other routing rule, leaving nothing 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 readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results carry expiry and instance counts, which is useful return-shape context in the absence of an output schema, but it says nothing about why a read-only list tool requires two private keys or how they are handled.

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 front-loaded sentence with no filler, and the scope qualifier appears before the trailing detail about returned fields. It is tight and earns its place, though the trailing clause makes it slightly less scannable than a pure verb-resource statement.

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

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

For a read-only list tool with 100% schema coverage and no output schema, the description supplies the one thing the schema does not: what each listed app row contains (expiry and instance counts). The remaining gap is the unexplained presence of credential parameters on a read operation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters in detail. The description only restates the owner default ('or a given Flux ID') and omits nameContains and the two key parameters entirely, adding no meaning beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb (Lists) and resource (every app registered by the owner), with the scope qualifier 'every app' making it distinguishable from the single-app sibling flux_get_app. It stops short of naming a sibling explicitly, so it earns a 4 rather than a 5.

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 verb and the owner/Flux ID qualifier, but there is no explicit when-to-use statement, no mention of when to prefer flux_get_app or flux_get_app_stats instead, and no note on prerequisites for the two private-key parameters.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description goes beyond them by disclosing the credit behavior for the unused part of an existing term and that FLUX is quoted at market rate. It does not mention that the schema exposes private-key parameters, but for a read-only quote this is a minor gap.

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 action and result, with the update/credit parenthetical kept tight. 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?

No output schema exists, and the description does explain the return content (USD plus FLUX at market rate), which is the critical piece for a quote tool. It is nearly complete, though it leaves the role of the private-key parameters unexplained.

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 67%, so the schema already documents key parameters (owner, expire, fluxIdPrivateKey, paymentPrivateKey). The description adds only the abstract notion of 'the given specification' and does not add meaning for the key params or the spec fields. Baseline 3 for a partly-covered schema with no added parameter 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+resource: 'Returns the Flux Cloud price for registering the given specification, or for updating it if an app of that name already exists.' This clearly distinguishes a pricing/quote operation from deployment siblings. It does not explicitly name alternatives like flux_deploy_app or flux_get_pricing, but the purpose is unambiguous.

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

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

Usage is implied (get a price before deploying) rather than stated. It does explain the register-vs-update branch cleanly, which is helpful context, but there are no explicit when-to-use/when-not conditions or named alternatives such as flux_get_pricing vs flux_deploy_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 already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuine value on top by disclosing the network-dependent phase, the specific checks performed (image reachable, architecture, ports, name availability), and the success return (node-formatted spec). It stops short of saying what happens on failure or clarifying that nothing is registered.

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, and the two-phase sequence is front-loaded before the return behavior. 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?

For a nested, key-accepting tool with no output schema, the description covers the process and result adequately, and annotations cover safety. It leaves minor ambiguity about failure behavior and whether any registration side effect occurs, which is slightly more important given the tool accepts payment and identity private keys.

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 75%, so the schema already documents most parameters, including the private-key handling conventions. The description's check list (architecture, ports, name availability) loosely maps to spec fields but adds no new syntax or constraint detail. Baseline 3 is appropriate.

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

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

The description names a specific verb+resource ('validate a specification') and describes the two-phase behavior (local rule checks then node verification). It distinguishes the tool's intent from write-path siblings like flux_deploy_app by stressing it behaves 'exactly as it would at registration,' but it never names an alternative tool outright.

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 this is a pre-deployment gate from 'exactly as it would at registration,' but there is no explicit when-to-use framing, no statement of the condition that selects it over flux_build_spec or flux_quote_app, and no mention of 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 already declare readOnlyHint=true and openWorldHint=true, and the description reinforces this with the note that repeated calls are safe until done=true, i.e. idempotent polling. It also discloses the default/max timeout and the rationale (fitting hosts with a 60 s tool timeout), real behavioral context beyond the annotations. It does not mention the private-key authorization requirements the schema hints at.

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: behavior and timeout budget first, then the return shape, then the polling-safety note. 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?

With no output schema, the description correctly carries the return contract (payment confirmations, spec acceptance, running instances with URLs) and the timeout semantics. The remaining gap is authorization context for the private-key parameters, though the schema provides per-parameter guidance.

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 67%, so the schema already documents txid, previousHash, and the private keys. The description adds genuine meaning only for timeoutSeconds (default 45, max 600, chosen to fit host timeouts) and implies what txid is for by describing the returned payment confirmations. Baseline 3 for a partially documented 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 (polls the network for a deployment to be accepted and its instances to run) plus the scope of polling via timeoutSeconds. The wait/poll framing separates it cleanly from sibling reads like flux_get_app and writes like flux_deploy_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?

"Safe to call repeatedly until done=true" gives a clear polling-loop usage pattern, which is the key operational guidance. However, it never names an alternative (e.g. flux_get_app for a single check) or states when not to use this tool, so routing against siblings 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.