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

With no annotations, the description carries more burden. It does disclose the temporary file and auto-approve command, adding some behavioral context, but it omits side effects, permissions, and failure behavior.

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

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

One sentence with a clear front-loaded purpose and a concise explanation of the method. No wasted words.

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

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

The description explains the core workflow but doesn't address return values, prerequisites like discover_bindings, or side effects. For a complex tool with nested objects and no output schema, this leaves notable gaps.

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 fully documents each parameter. The tool description adds no additional parameter meaning, warranting the baseline score of 3.

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 publishes a capture and describes the mechanism (writing a temp flow.yaml and running flowctl catalog publish). This distinguishes it from sibling tools like create_materialization by resource type.

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: it's for creating/publishing a capture, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusion criteria or prerequisites mentioned.

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 burden of behavioral disclosure. It reveals the exact implementation: writes a temporary flow.yaml and runs `flowctl catalog publish --source flow.yaml --auto-approve`, which implies an automated, approving publish. This adds meaningful context but omits side effects or failure behavior.

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

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

The description is a single, well-structured sentence with no fluff. It front-loads the action and provides a concrete implementation detail, making it efficient and easy to parse.

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 explains the publish mechanism but lacks context on prerequisites (e.g., flowctl and credentials), potential side effects on existing materializations, or expected return behavior. Given the absence of an output schema and the complexity of bindings, a bit more contextual guidance would be helpful, but the current description is not inadequate.

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

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

Schema description coverage is 100% and all parameters have helpful descriptions (e.g., name format, bindings meaning). The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the tool 'Publish a materialization', using a specific verb and resource. It distinguishes from sibling tools like create_capture by naming the resource type, but does not explicitly contrast with 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?

No guidance is provided on when to use this tool versus alternatives. The description explains the mechanism but not the use case context, prerequisites, or when not to use it, unlike the explicit alternative naming in higher-scoring examples.

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 present, so the description carries the full burden. It explicitly discloses that it writes a temporary flow.yaml, invokes flowctl discover, and returns the spec without publishing. This highlights the read-only nature and lack of persistent side effects, though it doesn't detail system requirements or cleanup.

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 core purpose. Every word is necessary; no fluff.

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 explains the operational flow (write temp file, run command, return spec) and the 'without publishing' caveat. However, it does not specify the format of the returned spec or any prerequisites, which is notable given there is no output 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?

All four parameters have schema descriptions that specify their meaning (e.g., 'Capture name', 'Connector'). The tool description does not add additional parameter-level detail, but the schema coverage is 100%, so the baseline of 3 applies.

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

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

Clearly states the tool's function—discovering bindings for a source connector—and distinguishes it from sibling tools like create_capture or task_status. The verb 'Discover' plus the specific resource make the purpose 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?

The description gives clear context that this is for discovering bindings, but does not explicitly say when it should be used instead of other tools, nor does it name alternatives. The 'without publishing' hint implies a dry-run, but no directed guidance is provided.

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

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

No annotations are provided, so the description carries the full burden of disclosure. It states the return behavior ('Returns a sample plus the full payload size') but does not mention whether the operation is read-only or has side effects like persistence.

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

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

Two concise sentences with zero waste. The primary action ('Generate synthetic records') is front-loaded, and the output detail ('Returns a sample plus the full payload size') is efficiently conveyed.

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 with three simple parameters and no output schema, the description covers the core purpose and return behavior. It could clarify what 'sample' and 'payload size' mean, but the schema fills in parameter details, making it reasonably 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 each parameter is already documented. The description hints that 'sample' corresponds to sample_size, but adds no significant meaning beyond the schema, meeting the baseline without exceeding 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 uses a specific verb 'generate' with resource 'synthetic records' and scope 'demo pipelines', clearly distinguishing it from sibling task-management tools. The purpose is immediately 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?

The phrase 'for demo pipelines' provides clear context for when to use the tool. It does not explicitly state when not to use it or mention alternatives, but the use case is well 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?

There are no annotations, so the description must carry the burden of disclosing behavioral traits. It implies a read-only list operation but doesn't explicitly confirm safety, output format, or potential side effects. Mentioning the wrapper adds minor implementation context but is insufficient.

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 consists of two short sentences, front-loads the primary action, and contains no redundant text. It earns a perfect score for conciseness.

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 with no output schema and no annotations, the description should clarify return values and note all allowed kinds. It mentions only three of the four kinds and doesn't describe whether the output is a list or how prefix affects results. It's adequate for a simple listing tool but has clear gaps.

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 provides full descriptions for both parameters (kinds and prefix) with 100% coverage, so the description adds little value. It omits the 'tests' enum value from the parenthetical list, potentially confusing users, but does not contradict the schema.

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

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

The description clearly identifies the tool's purpose as listing catalog entities (captures, materializations, collections) with a specific verb and resource. It distinguishes this from sibling task-specific tools like task_stats and task_logs. However, it omits the 'tests' kind that is allowed in the schema, creating a slight inconsistency.

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 no guidance on when to use this tool versus alternatives like pull_specs or task_stats. It only states what it does and that it wraps a shell command, without contextual usage cues 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 provided, the description carries the burden of disclosing behavior. It adds value by revealing the underlying command wrapper and the 'live' nature of the spec. 'Pull' implies a read-only operation, and 'for local inspection' suggests no side effects, though it falls short of explicitly stating read-only or safety guarantees.

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

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

The description is two sentences, front-loaded with the purpose, and wastes no words. The second sentence gives a practical wrapper reference without redundancy. Excellent conciseness.

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

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

For a single-parameter read tool with no output schema, the description is quite complete. It states what it does, the purpose, and the underlying command. The only minor gap is the lack of explicit mention of the return format or error behavior, but the simple nature of the tool keeps it adequately 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 schema already fully describes the 'task' parameter with 100% coverage, meeting the baseline of 3. The description further clarifies how the parameter maps to the `--name <task>` CLI flag, adding 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?

The description clearly states a specific action ('Pull a task's live spec') and the resource ('task's live spec'). It distinguishes itself from siblings by focusing on spec retrieval rather than stats, logs, or status, and the wrapped CLI command reinforces the exact function.

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 'for local inspection' provides clear context on when to use this tool. However, it does not explicitly mention alternatives or exclusions, so it lacks the explicit 'when not to use' guidance that would earn a 5.

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

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

With no annotations, the description carries the full burden. It discloses the key behavior: non-blocking, outputs everything currently available, and exits. This is sufficient for a simple read operation, though it does not mention permissions or return format details.

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

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

The description is two sentences: the first states purpose, the second explains the underlying command and behavior. Every sentence contributes value 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?

For a straightforward read tool with a complete schema and no output schema, the description covers purpose, behavior, and underlying command. It lacks explicit return format details, but that is not critical for this use case.

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 covers 100% of parameters with clear descriptions, so the baseline is 3. The description does not add extra meaning beyond the schema; it only references the collection in context of reading documents.

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 reads documents from a collection with a specific purpose: verifying data is landing. It uses a specific verb and resource, and distinguishes itself from sibling tools focused on task management and creation.

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 a clear use case ('to verify data is landing') and explicitly notes the non-blocking behavior, which guides when to use it. However, it does not explicitly name alternative tools or state when not to use it, though the sibling list makes that less necessary.

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 carries the burden. It discloses restart mechanism, checkpoint resumption, and data safety. Could mention potential downtime or failure behavior, but adequate.

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

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

Three concise sentences: action, side effect, and usage. No wasted words, front-loaded with the main purpose.

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?

Simple tool with one parameter; description covers purpose, mechanics, use cases, and data safety. Lacks explicit prerequisites like task existence, but sufficient for 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 has 100% coverage for the single parameter 'task' with 'Full catalog name.' Description adds no additional parameter context, so 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?

Description uses specific verb 'Force a connector restart' with clear mechanism (disable then re-enable), distinguishing it from siblings like set_task_enabled and 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?

Provides explicit use cases: 'Use to clear transient errors or load updated config.' Does not mention when not to use or alternatives, but context is clear.

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. It discloses the internal mechanism (toggling shards.disable and republishing), the behavioral consequences (stop/resume, no data loss), and the expected post-enable status delay (WARNING for 30-120s then OK). This is rich and transparent.

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

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

Two sentences, front-loaded with the action, and every sentence provides distinct operational detail. No wordiness or redundant restatement of the name 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?

For a simple two-parameter boolean toggle with no output schema, the description fully covers the mechanism, operational impact, timing, and data-safety behavior. An agent has enough context to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters (task, enabled). The description adds no per-parameter detail beyond what the schema already provides, so 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 opens with 'Enable or disable a task by toggling shards.disable', a specific verb and resource, and clarifies the operational effect. This distinguishes it clearly from read-only siblings like task_status and task_health, and from restart_task.

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 clearly implies when to use the tool: disabling stops processing, re-enabling resumes from the last checkpoint. It gives useful context for pause/resume scenarios, though it doesn't explicitly name 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It does disclose that it aggregates multiple data types, which is a key behavior. However, it does not explicitly state that it is read-only, describe the return format, or mention any side effects or caveats, leaving room for ambiguity.

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

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

The description is a single, front-loaded sentence that communicates the core purpose and scope without any filler. It is concise and well-structured.

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

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

The tool has a clear description, but given no output schema and no annotations, the description doesn't fully explain what the returned health check data looks like or provide any caveats. The parameter schema is well-documented, but overall context is sufficient yet not rich. It's a minimum viable description with clear gaps.

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%: both 'task' and 'since' are described in the schema. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function as an 'end-to-end health check' that combines status, throughput, and error-level logs. This specific verb-resource pairing and the mention of combining data distinguish it from sibling tools like task_status, task_stats, and task_logs.

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 use by indicating this tool is a one-call aggregate of status, throughput, and error logs. It implies when to use it (when a combined view is needed), though it does not explicitly name 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?

With no annotations, the description carries the full burden. It discloses that the tool wraps `flowctl logs`, which is a concrete behavioral detail (external command execution). However, it does not mention output format, ordering, or error behavior, leaving gaps.

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 front-loaded with the core purpose. The two sentences are efficient, though the first is a noun phrase rather than a proper sentence. No wasted words.

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

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

The description covers the tool's basic role and underlying command, but omits the output format and does not mention how `limit` or `level` map to the CLI command. Given the schema covers parameters well, the description is adequate but not comprehensive for a no-output-schema 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 input schema provides complete descriptions for all four parameters (100% coverage), so the baseline is 3. The description adds nothing beyond the schema's own parameter details, merely repeating the level filtering concept.

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 as returning recent task logs, and the wrapper line specifies the underlying command. It lacks an explicit verb like 'list' or 'fetch', but the intent is unambiguous and it is distinct from sibling tools like task_stats or task_health.

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

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

No guidance is provided on when to use this tool versus alternatives such as task_status or task_health. The mention of optional level filtering is parameter detail, not usage 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?

There are no annotations, so the description must carry the burden. It adds useful context by naming the underlying flowctl command and parameter mapping, but it does not disclose whether the operation is read-only, any rate limits, or the exact output structure beyond 'throughput and document counts'.

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 followed by a command template, conveying the purpose and underlying wrapper without unnecessary verbosity. Every element contributes.

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 relatively simple tool with two parameters and no output schema, the description adequately covers purpose and command mapping. It hints at the return type (throughput and document counts), which is sufficient, though some agents may desire explicit output format details.

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

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

Schema coverage is 100% with both parameters well-described. The description adds a minor layer by mapping them to the command-line flags, but this is largely redundant. The baseline of 3 applies since the schema already provides comprehensive parameter documentation.

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 provides throughput and document counts for a task, which is a specific resource and data type. It distinguishes from sibling tools like task_logs and task_health, though it lacks an explicit verb such as 'retrieve'.

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 no guidance on when to use this tool compared to alternatives like task_status or task_health. It only mentions that it wraps a command, without any when-to-use or when-not-to-use scenarios.

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 behavioral transparency burden. It mentions the wrapped CLI command and status types but does not explicitly state whether the operation is read-only, what error behaviors occur, or any permissions needed.

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

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

The description is two sentences, front-loaded with the core purpose, and efficiently includes the underlying command and status types 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?

For a simple status-check tool, the description covers purpose, output format (JSON via CLI), and status types. However, with no output schema and no annotations, it lacks details on exact response structure or error handling, though it is largely adequate.

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 already provides comprehensive descriptions for both parameters (task and connected) with an example, covering 100% of parameters. The description adds no additional parameter detail, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool provides control-plane status for one task, naming the resource and action. It distinguishes itself from list_tasks by focusing on a single task and from task_stats/task_logs via the status types, but does not explicitly mention sibling 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 provides no guidance on when to use this tool versus alternatives like task_health, task_stats, or task_logs. It simply defines the function without giving usage context or exclusions.

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