Fluxion Bus

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

The description uses 'Request cancellation' but does not disclose whether the cancellation is asynchronous, what success/error responses look like, or if there are side effects (e.g., resource cleanup). With no annotations provided, the description carries the full burden and falls short.

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 short and to the point, with no redundant words. However, it lacks structural elements like examples or additional context that could improve clarity.

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

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

Given the tool has an output schema (not shown) and zero annotation coverage, the description should provide more details about return values, error handling, or cancellation semantics. It is incomplete for a cancellation request.

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 only parameter 'run_id' lacks any description in the schema or the tool description. The description adds no meaning beyond the parameter name, failing to clarify format, source, or constraints.

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

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

The description clearly states the action ('cancel') and the resource ('active sub-agent run'), distinguishing it from sibling tools like 'run_subagent' (creation) and 'revert_subagent_run' (revert).

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

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

No explicit guidance on when to use this tool versus alternatives such as 'get_task_status' or 'revert_subagent_run'. The purpose is implied but no context on prerequisites or 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?

With no annotations, the description fully carries the burden of behavioral disclosure. It details the destructive nature (terminating the whole process group when owned by this process), the no-op with owner reporting when another process owns it, and the INTERRUPTED close-out when the owner is gone. This is rich, essential context for a forceful operation.

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 three short, purposeful paragraphs: first states the core function, second gives usage triggers, third explains behavioral outcomes. Every sentence earns its place with no fluff or repetition, and the most important information is front-loaded.

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

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

The description thoroughly explains the tool's role within the broader lifecycle, including ownership semantics and three possible branches. The output schema likely handles return values, so no further description is needed. For a cancellation tool with significant edge cases, this is fully complete.

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

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

The input schema has one required parameter, run_id, with only a 'Run Id' title and no description. The tool description does not mention run_id at all beyond referencing 'a run' generically, so it adds no semantics about ID format, validation, or usage. With 0% schema description coverage, the description should compensate but does not.

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

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

The description opens with 'Cancel a run that plain cancel_subagent_run cannot reach,' which uses a specific verb, identifies the resource (a run), and clearly distinguishes this from the sibling cancel_subagent_run. It immediately conveys the tool's unique purpose as a fallback escalation.

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 provides explicit when-to-use guidance: after cancel_subagent_run reports the run is unknown, or when a run has been non-terminal for too long. It also explains the three ownership scenarios and their outcomes, giving the agent clear context for when to invoke this tool and what to expect.

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

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

With no annotations, the description carries the full burden and does so admirably. It discloses that config is read once at startup, that dev and installed copies can have separate .env files, and explains the meaning of config_file_changed_since_start. This is rich behavioral context beyond a simple 'get status'.

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

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

The description is compact and front-loaded, opening with a clear question that summarizes the purpose, then listing the return scope, and closing with a practical usage tip. Every sentence earns its place without unnecessary verbosity.

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

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

Given the tool's complexity and the existence of an output schema, the description is complete. It explains what information is returned, highlights a key diagnostic scenario (config not taking effect), and provides necessary background about startup config loading. No critical context 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. The description correctly adds no parameter-specific details because none 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 clearly identifies the tool's function: reporting which Fluxion installation is serving the session and its current state. It enumerates specific details returned (code root, .env, queue/worker state, locks), which distinguishes it from sibling tools focused on projects, agents, and tasks.

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 explicit guidance to use when a config change appears ineffective, explaining the startup-only config read. This is clear context, though it does not explicitly state when not to use the tool or mention alternative tools.

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?

No annotations are provided, and the description only says 'Return,' implying a read operation. It does not disclose behavior on missing keys, authorization requirements, or any side effects. Minimal transparency.

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

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

Extremely concise at one sentence, front-loading the action and resource. However, brevity sacrifices necessary detail, earning a high score for conciseness but not for completeness.

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 only one parameter and an output schema, the description should provide more context on return format, error handling, or relationship to sibling tools. It lacks sufficient context for reliable tool selection.

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 has 0% description coverage; the description only mentions 'by key' without clarifying what constitutes a key (e.g., name or ID). The parameter name 'project' is uninformative, and no further semantics are added.

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 'Return one configured Fluxion project by key,' clearly specifying the action, resource, and scope (one project). This distinguishes it from sibling 'list_projects' which returns all projects.

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

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

No guidance on when to use this tool versus alternatives like 'list_projects'. While 'one' vs 'list' implies distinction, explicit when-to-use or when-not-to-use context is missing.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It does this excellently by explaining that stdout/stderr are the agent's own output, that the executor_log is returned separately with glog chatter filtered out, and that raw=true provides the unfiltered record. This goes beyond what a typical tool description provides.

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 well-structured, opening with the core purpose and then adding necessary detail about output composition. Every sentence adds value, explaining not just what happens but why (avoiding buried answers). It is thorough without being verbose.

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

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

Given the tool's complexity and the presence of an output schema, the description is complete. It covers the nuanced behavior of include_output and raw, the separation of executor_log, and the filtering rationale. The absence of explicit return value details is acceptable because an output schema exists.

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

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

Schema description coverage is 0%, so the description must compensate. It does so by explaining include_output and raw in detail, clarifying their effects on the returned result. run_id is self-explanatory from its name, so the description covers the critical parameter semantics effectively.

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

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

The description clearly states the tool 'Get a model-friendly result view' with the option for raw output, specifying the verb 'Get' and the resource 'task result'. This distinguishes it from siblings like get_task_status (status vs result) and list_subagent_runs (list vs single result).

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 provides clear context on when to use the tool: when a model-friendly result view is needed, optionally with raw output. It explains the behavior of include_output and raw, but does not explicitly name alternatives or exclusions, like using get_task_status for status checks.

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

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

With no annotations provided, the description carries the full burden and does so richly. It discloses blocking behavior with wait_ms, the cap on wait time (60s), the fact that a still-running task returns RUNNING, the compact vs detailed response distinction, and the environment variable override. This goes well beyond a simple status getter.

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 well-structured and front-loaded with the core purpose. The first paragraph states exactly what the tool does. The second explains response options, and the third explains long-polling behavior. Each sentence contributes valuable information with 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 the tool's complexity, this description is highly complete. It covers the default response, optional detail, long-polling behavior, timeout cap, and environment variable. Since an output schema exists, the description need not enumerate return fields, and it doesn't unnecessarily repeat what structured data could convey.

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 0%, so the description must compensate. It thoroughly explains detail (compact vs full metadata) and wait_ms (long-poll, blocking, cap). run_id is only implicitly referenced ('for a Fluxion run'), but its meaning is self-evident from the schema and name. Overall, the description adds significant meaning for two of three parameters.

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

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

The description clearly states the tool gets 'model-friendly status and next action for a Fluxion run,' using a specific verb and resource. It distinguishes the tool from siblings like get_task_result by focusing on model-friendly, polling-oriented output, though it does not explicitly name alternatives.

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 context for when to use the tool: it is designed for polling, with a compact default response and optional long-polling via wait_ms. It does not explicitly mention when not to use it or compare with sibling tools like get_fluxion_status, but the polling use case is clearly 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?

With no annotations, the description fully carries the burden. It discloses that the tool uses different CLI backends (Codex, Antigravity, Claude Code), that Claude Code lacks a stable catalog so aliases are used, and that catalogs are enriched with local price tables where possible. It also clarifies that price_references[] is not an override and that provider/auth remain settings-level config. This is rich, honest behavioral 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?

The description is structured with a lead sentence stating the core purpose, followed by targeted paragraphs explaining backend behavior and usage caveats. Every sentence adds value—no fluff or repetition. The length is appropriate for the complexity of the tool.

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?

Despite no annotations and an output schema that is not shown, the description explains what is returned (models[], price_references[]), how it behaves per agent, and how to use the output. It covers edge cases (Claude Code) and explicitly warns about the validity of price references. For a list tool, this is complete and 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 0% for the two parameters (agent, project). The description says 'for one executor' which hints at the agent parameter, and mentions different agent CLIs, but does not explicitly explain 'project' or the default/resolution of 'auto'. The description adds some context but does not fully compensate for the absent schema descriptions.

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

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

The description opens with a specific verb+resource: 'List likely selectable models for one executor, sorted high to low.' It clearly distinguishes this from sibling tools like list_projects (projects) and list_subagent_runs (runs), and the subsequent details about per-agent CLI backends reinforce the unique scope.

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

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

The description says 'Pass a chosen models[].id to run_subagent(model=...)' which tells the agent exactly how to use the result. It also warns that price_references[] is context-only and not a valid override. However, it does not explicitly state when *not* to use this tool or select among alternatives, though the context implies it is the precursor to run_subagent.

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?

No annotations are provided, so the description bears full burden. It only states the tool lists projects, leaving out behavioral details like authentication requirements, caching behavior, or whether it shows all or only accessible projects. For a simple list, this may suffice, but lacks depth.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the key action and resource.

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 zero parameters, an output schema, and simple listing functionality, the description is complete enough for an agent to understand the tool's purpose. However, missing behavioral details slightly reduce completeness.

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?

No parameters exist, and schema coverage is 100%. The description adds no parameter information since none is needed. Baseline of 4 for zero parameters is appropriate.

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

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

The description clearly states a specific action: 'List configured Fluxion projects'. It uses a verb+resource structure and distinguishes from sibling tools like 'get_project' (singular) and 'run_subagent' (action).

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

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

The description implies usage for listing projects but does not provide explicit guidance on when to use this tool vs alternatives like 'get_project' or 'run_subagent'. No exclusions or conditional advice.

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?

No annotations provided, so description must compensate. It says 'list recent ... from local task store' implying read-only, but lacks explicit disclosure of safety, authentication requirements, or return format.

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?

Single sentence, concise but underinformative. Lacks crucial details like filtering capabilities.

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 5 undocumented optional parameters and no annotations, the description is insufficient. Existence of output schema not leveraged in description.

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 0%, and description does not explain any of the 5 parameters (agent, limit, status, project, agent_path_prefix). No added meaning beyond parameter names.

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

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

Description clearly states verb 'list' and resource 'sub-agent runs' from 'local task store'. It's specific but doesn't distinguish from sibling tools like get_task_status.

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

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

No guidance on when to use this tool versus alternatives (e.g., get_task_status, get_task_result). Implied usage only.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains that only runs with a dead owning process are affected and that live processes are never touched. It also clarifies the marking as INTERRUPTED and the automatic behavior, providing meaningful safety 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?

The description is concise and well-structured. It opens with the core action, then explains the problem and the safeguard, and ends with an important automatic behavior note. Every sentence contributes valuable information without redundancy.

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

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

Given the tool's simplicity (no parameters) and the existence of an output schema, the description is complete. It covers purpose, behavior, scope, safety, and automatic triggering, which is sufficient for an agent to understand when and how 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?

The tool has zero parameters, and the schema is empty. Therefore, there are no parameter semantics to clarify. The description does not need to compensate for missing schema information, making the baseline score of 4 appropriate.

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

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

The description clearly states the tool's function: closing out runs whose owning Fluxion process no longer exists. It uses specific language like 'marks those INTERRUPTED' and distinguishes itself from related tools by focusing on reconciliation, not listing or cancellation.

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 provides clear context for when this tool is relevant: after a process dies mid-run, leaving tasks stuck as RUNNING. It also notes automatic invocation at Fluxion startup, which helps the user understand when manual use is necessary. However, it does not explicitly mention alternatives or 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?

No annotations exist, so the description must bear the full burden. It only states the action without disclosing side effects, destructive nature, permissions required, or behavior on invalid inputs (e.g., non-existent run_id).

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

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

The description is a single, concise sentence with no redundant words, effectively communicating the core action.

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

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

The description omits important contextual details such as what 'recoverable text-file changes' means, the return value (despite an output schema existing), and any prerequisites. Given the simple parameter count, it feels incomplete.

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

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

The input schema has 0% description coverage and the description adds no meaning beyond the parameter name 'run_id'. It does not explain what a run_id is, its format, or how to obtain it.

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 specifies the action (revert) and the resource (recoverable text-file changes for one Fluxion run). It distinguishes from sibling tools like 'cancel_subagent_run' and 'run_subagent' by focusing on reverting changes rather than canceling or starting runs, providing a clear purpose.

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

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

No guidance on when to use this tool vs alternatives is provided. The description does not mention when not to use it, any prerequisites, or relationships to other tools like 'cancel_subagent_run'.

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

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

With no annotations provided, the description carries the full burden — and it delivers. It discloses the queued-return behavior, that timeout_sec is not the runtime limit, that a pending WORKSPACE_NOT_AUTHORIZED is a human decision rather than a transient failure, that retrying immediately cannot succeed, that resumed Antigravity runs may reconcile the workspace, and that diff_summary.additions/deletions are always 0 with lines_counted=false to avoid misleading numbers. These are exactly the behavioral traits an agent cannot infer from a schema.

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

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

The description is long, but every paragraph earns its place given 18 parameters plus async, authorization, and session semantics; the essential async/wait model is front-loaded. It loses a point for being a dense wall of paragraphs — parameter-by-parameter explanations in a long prose format lack visual scannability for an agent, and the wait_for_result/timeout story is told with some redundancy across the first and third paragraphs.

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 tool of this complexity — async lifecycle, authorization gate, session reuse, per-run model overrides, and result-interpretation traps — the description is remarkably complete. It covers the full operational flow (submit → poll → collect, with the authorization detour), the actual runtime cap (settings.task_timeout_sec), and even interprets output semantics (changed_files authoritative, artifacts only via ACTIONS_JSON.upload_files) beyond what the output schema would convey. The four lightly-documented parameters are minor and carry sensible defaults.

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 0%, so the description must compensate — and it covers most of the 18 parameters in depth, going far beyond names: workspace path resolution against server workspace_root, agent enum values, profile/mode defaults vs. edit-task recommendations, task_name slugification rules, the price_references trap for model, reasoning_effort per-model validity with the MODEL_UNRESOLVED fallback, and thread/session_policy reuse semantics. Minor deduction: client_id, parent_path, include_stdout, and include_subagent_preamble receive no explanation, which with 0% schema coverage leaves small gaps.

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 opening sentence 'Submit a local Fluxion executor as a sub-agent task' names a specific verb and resource, and the submission role is unambiguous against the sibling set (wait_for_authorization, get_task_status, cancel_subagent_run, get_task_result all handle lifecycle stages, not submission). The description goes further by clarifying the async submission semantics, so an agent knows exactly what this entry point does.

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 explicit when-to-use guidance with named alternatives: use wait_for_result=true for 'small smoke checks', prefer the default for long/open-ended work, call list_agent_models before choosing a model, use list_projects to resolve configured projects, and call wait_for_authorization instead of retrying on a pending decision. It also states explicit exclusions: do not pass price_references[].id, and do not retry until the wait reports approved. This is exemplary routing and 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?

With no annotations, the description carries the full burden, and it delivers: it discloses that the call blocks, that wait_ms is capped, that an unanswered request returns pending, that the agent should act on status rather than return, and that certain statuses mean the request id is finished. It also notes the human-approval dependency.

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 longer than average but every sentence earns its place. It front-loads the core purpose, then moves from trigger condition, to polling behavior, to status-specific actions. The bullet list makes the status semantics scannable rather than burying them in prose.

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?

This is a complex tool with no annotations, yet the description covers trigger, blocking behavior, timeout handling, retry rules, and every status outcome. The output schema exists and is supplemented by the explicit next_action/should_retry explanation, so nothing critical is left to inference.

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 0%, so the description must compensate, and it fully does. It explains where authorization_request_id comes from (the run_subagent error), and gives detailed semantics for wait_ms: long-polling, capping, and repeated polling on timeout. This goes well beyond the bare schema.

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

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

The opening sentence states a specific verb and resource: 'Wait for the user's decision on a pending workspace authorization request.' It immediately ties the tool to the run_subagent error condition, so an agent can distinguish this from listing, canceling, or status tools without opening the schema.

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

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

The description explicitly states when to call this tool (after run_subagent returns WORKSPACE_NOT_AUTHORIZED with pending=true), why retrying immediately cannot succeed, and when to keep waiting or stop waiting. It also gives action-by-action retry instructions for each status, which is unusually clear operational guidance.

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