ActionDock

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only that it returns both status and result, which is useful but minimal beyond the structured fields.

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; every word carries information about what is retrieved.

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 one-parameter read tool with full annotations and an output schema, the definition is nearly sufficient—return values need not be explained and the job_id origin is documented in the schema. The only real gap is the missing polling-vs-waiting routing against wait_for_job.

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

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

Schema description coverage is 100%, and the schema itself even documents that job_id comes from run_action, so the description has no compensating work to do. Baseline 3 is appropriate.

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

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

States a specific verb (get) and resource (status and result of an action job), which is more precise than the bare title 'Get job'. It does not, however, distinguish itself from the closely related sibling wait_for_job, which an agent would also consider when retrieving job results.

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 guidance on when to use this tool versus wait_for_job or list_job_reconciliations. The phrase 'current status' hints at a non-blocking poll, but the choice between polling and waiting is left entirely 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 readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat that. The description adds valuable behavioral context by disclosing that the response includes input schemas and side-effect flags, which enriches the agent's understanding of what the result contains.

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 that front-loads the core function and then specifies the valuable output contents. Every word contributes meaning, with no redundant or filler language.

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, strong safety annotations, and the existence of an output schema, the description is complete for agent decision-making. It tells the agent exactly what the tool lists and what the result includes, and no critical operational details are 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 has zero parameters, so per the baseline rule a score of 4 applies. The description avoids fabricating parameter details and correctly focuses on the output, which is the only meaningful aspect of the call.

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

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

The description uses a specific verb and resource: 'List every action available to the agent,' and explicitly states what the output includes (input schemas and side-effect flags). This clearly distinguishes it from sibling list tools like list_connections and list_events, which target specific resource categories.

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 this tool is for discovering available actions, but it does not explicitly state when to prefer it over alternatives or when not to use it. There is no mention of sibling tools or exclusion criteria, so usage guidance is only implied rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds meaningful behavioral context beyond annotations by stating that credentials are never returned, which is a useful guarantee for an agent deciding whether to call this 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?

The description is two short sentences with no filler. The primary action and resource are front-loaded, and the key behavioral guarantee is added in the second sentence. Every word 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 parameters, an output schema present, and annotations covering idempotency and read-only behavior, the description is complete. It covers what is listed, scope, and the important credential-privacy note. An agent has everything needed to invoke this tool correctly.

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

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

There are zero parameters, so the description need not explain parameter meaning. The baseline for zero parameters is 4; the description adequately defines what the tool returns without any parameter-specific guidance being necessary.

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

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

The description states a specific verb ('List'), a clear resource ('workspace-approved HTTPS API connections'), and adds scope detail ('method/path allowlists'). This clearly distinguishes it from siblings like list_actions, list_events, and list_usage, which target different resource types.

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: the tool is for listing workspace-approved connections, not for modifying or running them. It doesn't explicitly name alternatives or exclusions, but the resource distinction is obvious from the sibling names and the description itself.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scoping ('recent', 'job and callback events') but does not disclose additional behavioral traits such as ordering guarantees, pagination behavior, or retention semantics. It does not contradict 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 sentence that front-loads the core behavior ('List recent job and callback events') and then states the purpose. There is no filler, repetition, or unnecessary background.

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

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

For a simple read-only list tool with one fully documented parameter and an output schema, this description is complete. An agent has enough information to select and invoke the tool correctly: what it lists, the recency aspect, and the purpose.

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%: the 'limit' parameter already has a full description with default, minimum, and maximum. The tool description adds no parameter-specific meaning, 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 names a specific verb ('List'), a specific resource ('recent job and callback events'), and a purpose ('workflow continuation and audit'). This clearly distinguishes it from sibling tools like list_actions and list_connections.

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?

'For workflow continuation and audit' gives clear context for when this tool is appropriate, and the mention of 'recent' implies this is for reviewing history rather than blocking on an outcome. It does not explicitly name alternatives or exclusions, but the context is strong enough for a simple list tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond those flags: observations are 'append-only', they are unverified owner reports, and agents cannot record observations. This clarifies both the data model and the trust boundary, which is exactly the kind of behavioral caveat an agent needs.

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

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

Three short sentences with no filler. The first sentence states the action and object, the second adds necessary epistemic caveats, and the third states an important agent restriction. Every sentence earns its place and the structure is easy to scan.

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 listing tool with full schema coverage, an output schema, and safety annotations, the description is complete. It explains the purpose, the provenance and reliability of the data, and the agent's inability to write. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, and each parameter already has a meaningful description: limit has bounds and ordering, before explains pagination tokens, and job_id names its source. The description itself adds no parameter-specific detail, so it correctly stays at the baseline 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 uses a specific verb ('Read') and identifies a precise resource: the owner's append-only observations about an unknown write. It also distinguishes itself from status/verification/retry tools by explicitly stating it is 'not verified provider facts, a changed job status, or permission to retry', making its 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 for when to use the tool: to inspect owner-side reconciliation evidence for an unknown write. It explicitly states what the observations are not, which helps an agent avoid misusing the tool as a source of verified facts or retry authorization. It does not name a specific sibling alternative, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral detail that the total is for the current UTC month, which is useful context beyond the schema. It does not describe pagination behavior or what happens when limit is exceeded, but the schema's maximum of 200 covers that constraint. No contradiction with annotations.

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

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

The description is a single sentence that front-loads the primary action ('List metered action debits') and appends the secondary output (monthly total). Every word earns its place; there is no redundancy or filler.

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

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

For a simple read-only list tool with one optional parameter, a full output schema, and annotations covering safety and idempotency, the description is nearly complete. The only minor gap is that it does not explicitly mention pagination or the default limit behavior, but the schema's default and maximum values cover the practical needs. The tool is simple enough that this is 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?

Schema description coverage is 100%, so the single parameter 'limit' is fully documented in the schema. The description does not add any additional parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the full burden and the description adds no extra semantic value.

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

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

The description states a specific verb ('List') and resource ('metered action debits') and adds the current UTC-month usage total, which clearly distinguishes it from sibling list tools like list_actions, list_connections, and list_events. It is clear but does not explicitly name a sibling alternative, so it falls 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?

The description implies usage context: it is for viewing metered action debits and the monthly total. However, it does not explicitly state when to use this tool versus alternatives such as list_actions or list_events, nor does it mention any exclusions or prerequisites. The context is clear enough for basic selection but lacks explicit routing guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds meaningful context beyond them: external writes require workspace-owner approval in the dashboard, the owner is emailed, and wait_for_job blocks until the decision. It still does not clarify irreversibility or failure behavior of the external write itself.

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 tightly packed sentences with the core purpose front-loaded and the approval/blocking behavior following immediately. No filler text.

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

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

With an output schema present, return details need not be explained, and the approval flow is covered well. Minor gap: no note on what happens if approval is denied or how long the job persists.

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

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

Schema description coverage is 100%, so the schema already fully documents action, input, workflow_id, workflow_name, and idempotency_key. The description adds no parameter-level detail beyond that baseline, so a 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+resource ('Create an action job') and names the related sibling wait_for_job, so an agent can distinguish it from get_job/list_jobs style siblings. It does not, however, describe what an 'action' is beyond the schema's reference to list_actions.

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 when this tool is invoked (submitting an action) and points at wait_for_job as the blocking companion, which is useful routing. But it gives no explicit when-not-to-use guidance or comparison against siblings like get_job or list_actions.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: it lists the terminal states and explains that a timeout returns awaiting_approval and that the caller should call again to keep waiting. It does not cover auth, rate limits, or error behavior.

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

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

Three sentences, all front-loaded and purposeful. The purpose and terminal states come first, followed by timeout behavior and a practical caveat about client tool timeouts. No sentence is wasted.

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

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

An output schema exists, so the description need not explain return values, and annotations cover safety. It explains the waiting semantics, timeout behavior, and retry guidance well. The only notable gap is lack of explicit contrast with sibling get_job for when immediate retrieval is preferable.

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 both job_id and timeout_seconds fully. The description adds no parameter syntax or meaning beyond what the schema provides, making the baseline of 3 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 states a specific verb and resource: waiting for an action job to reach a decision or final state. It enumerates the terminal states, making the tool's scope clear. However, it does not explicitly distinguish this tool from sibling get_job or run_action, which would help an agent route correctly.

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: wait for a job to reach a final state, and call again if the timeout returns awaiting_approval. The description provides behavioral context for repeated calls but does not explicitly state when to use this instead of get_job or the other siblings, nor does it mention any prerequisites beyond what the schema already contains.

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