Company Jobs & Hiring Signals

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond the annotations: the call is a no-op for SUCCEEDED/FAILED/ABORTING/ABORTED/TIMED-OUT runs, and the response returns the updated run details. It does not mention permission requirements or failure modes.

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?

Front-loaded with the core action and its status preconditions before the USAGE block, and no sentence is wasted. The USAGE EXAMPLES lines are thin (one is a bare restatement of the required runId) but the graceful variant does demonstrate a real parameter usage.

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 values need not be detailed, and the description correctly just notes that updated run details come back. Purpose, preconditions, and usage are all covered; only permission/auth context is missing for a destructive, openWorld=false operation.

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

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

Schema description coverage is 100% and both parameters (runId, gracefully with its 30-second timeout) are fully documented in the schema, so the baseline is 3. The description adds little parameter meaning beyond the example 'Gracefully abort run y2h7sK3Wc', which only loosely illustrates the gracefully flag.

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

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

States a specific verb and resource ('Abort an Actor run') and narrows scope with the precondition 'currently starting or running', which makes the operation unambiguous. It never names a sibling such as get-actor-run to contrast against, but the destructive abort semantics are self-evidently distinct from the read-only tools in the sibling list.

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

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

'Use when you need to stop a run that is taking too long or misconfigured' gives a clear triggering condition, and the status no-op list functions as an implicit when-not-to-use rule for terminal runs. No alternative tools or host-level prerequisites (auth, workspace scoping) are offered, so it stops short of a full routing guide.

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, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the blocking semantics and 45s cap of waitSecs, the meaning of summary (describes the past) and nextStep (prescribes one interpolated follow-up), which an agent needs to interpret the response.

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?

Front-loaded with the purpose, then USAGE, then examples, with every line carrying information: field list, summary/nextStep semantics, and the waitSecs contract. No filler sentences, and the examples are short and directly actionable.

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 values need not be explained, yet the description usefully characterizes summary and nextStep so the agent can act on them. Purpose, parameters, blocking behavior and examples are all covered; only auth/permission prerequisites for reading another Actor's run are unstated, which is a minor gap.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema with min/max/default and terminal-state enumeration. The description's waitSecs line ('0-45, default 30, waits up to that many seconds for terminal status') largely restates the schema, adding no syntax or format beyond it, so the baseline 3 applies.

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

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

The description gives a precise verb+resource ('Get detailed information about a specific Actor run') and enumerates the returned fields (status, storages, stats, summary, nextStep). It does not explicitly contrast itself with the sibling abort-actor-run, but the phrasing 'a run started by any Actor-running tool' makes its read-only inspection role clear.

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 USAGE section states when to reach for it ('check the status of a run started by any Actor-running tool') and how to make it block via waitSecs > 0, reinforced by two concrete user_input examples. It stops short of stating when NOT to use it (e.g. versus abort-actor-run or a listing tool), so it is clear context without 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 annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral context: returns rows themselves, default limit of 20, and clean=true behavior. It also clarifies the nature of the return value beyond the 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?

Well-structured with clear USAGE and USAGE EXAMPLES sections. Some redundancy ('Get items (rows)...' and 'Returns the rows themselves...') but overall efficient and front-loaded with 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?

Given the tool has 8 parameters, an output schema, and rich annotations, the description adequately covers key behaviors, usage triggers, and examples. It doesn't explain every parameter but relies on the schema for that, which is appropriate.

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 baseline is 3. The description adds extra meaning by explaining default limit (20) and the clean=true shortcut, which supplements the schema. It also provides examples for fields usage, though most parameter semantics are in 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?

Description clearly states the tool gets items (rows) from a dataset and explicitly distinguishes it from metadata, counts, or schema. It names the exact resource (dataset items) and the action (get), and provides direct trigger phrases for when to use it.

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 ('when the user provides a datasetId and asks to retrieve results...'), and clarifies what it is not for (metadata, counts, schema). However, it does not name alternative tools explicitly, only implies them.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint as false. The description adds valuable behavioral context beyond this: the exact key name requirement and the preservation of Content-Encoding with automatic client decompression. No contradictions 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 well-structured with a concise opening definition, a short behavioral note, and clear usage examples. Every section earns its place without unnecessary 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?

For a simple two-parameter read-only tool with full schema coverage, an output schema, and strong annotations, the description covers the essential context: how to target a record, what to expect (Content-Encoding), and when it applies. The sibling context also helps differentiate it from listing operations.

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?

Input schema coverage is 100%, so the schema already documents both parameters. The description adds usage examples and the 'exact key name' requirement, but these are minimally additive beyond the schema's own property 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 uses a specific verb and resource: 'Get the value stored under a specific key in a key-value store.' It also distinguishes itself by explicitly stating this is 'a single record, not a listing of all keys,' which separates it from sibling tools like get-dataset-items.

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 usage context: 'Use when you need to retrieve a specific record (JSON, text, or binary) from a store.' It does not name alternative tools explicitly, but the 'not a listing of all keys' phrase gives implicit exclusion guidance for listing-style operations.

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