Greenhouse, Lever & Ashby Jobs + Salary

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the no-effect-on-terminal-states rule, which is exactly what makes the idempotent hint meaningful, plus the fact that updated run details come back. It omits auth/permission requirements and any rate-limit 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?

Front-loaded with the core action and the state constraint, and every prose sentence earns its place. The 'USAGE EXAMPLES' block of raw user_input lines is mostly decorative and pads the definition slightly.

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 spelled out, and the description still notes that updated run details are returned. For a two-parameter mutation with full annotation coverage, only auth requirements are unaddressed, 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 description coverage is 100%, so both parameters and the 30-second graceful-abort timeout are already documented in the schema. The description only gestures at 'gracefully' via an example, adding no syntax or semantic meaning beyond the schema. 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?

Specific verb (Abort) plus resource (Actor run) and a state qualifier ('currently starting or running'), which immediately distinguishes it from siblings like call-actor and get-actor-run. An agent can select it 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?

Explicit when-to-use ('stop a run that is taking too long or misconfigured') and an explicit no-op condition (terminal statuses such as SUCCEEDED, FAILED, ABORTED, TIMED-OUT). It does not name an alternative tool or describe prerequisites, 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 readOnly, idempotent, non-destructive, but the description adds real behavioral context beyond them: the summary vs. nextStep semantics, and that waitSecs blocks for up to 45s (default 30) before returning the current state. This is substantive added value, though it doesn't cover error/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 purpose, then segmented into Returns/USAGE/EXAMPLES blocks. Every line carries information, though the two usage examples are somewhat redundant with the USAGE prose, adding minor length.

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 and 100% parameter coverage, the description need only orient the agent, which it does fully: purpose, when to use, wait semantics, and concrete invocation examples. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by framing waitSecs as a blocking/wait mechanism with its cap and default, and by describing what runId's run produces. Slight above-baseline value over the schema text.

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 ('Get detailed information about a specific Actor run') and enumerates the returned result fields (status, storages, stats, summary, nextStep). It does not explicitly distinguish itself from siblings like call-actor or abort-actor-run, so it falls just short of the 5 benchmark.

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 block names the condition ('check the status of a run started by any Actor-running tool') and explains when to pass waitSecs > 0 to block until terminal. It gives clear context but stops short of explicit exclusions or naming the sibling to use for other run operations.

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 cover safety (readOnly, idempotent, non-destructive), so the description adds value by disclosing the default limit of 20, what clean=true does, and that results are the raw rows. Return-shape details are largely deferred to the existing output schema, which is appropriate.

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 purpose and the anti-scope sentence, followed by short usage notes and examples. Slightly redundant in repeating the limit default and the clean flag across sections, but nothing wasteful enough to hurt.

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 tool with full schema coverage and an output schema, the description supplies the purpose, trigger, and key defaults an agent needs. Pagination interaction (offset/limit) and flatten behavior are left to the schema, which is reasonable given the 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 100%, so the schema already documents all eight parameters in depth. The description only restates the default limit and clean=true semantics, adding little beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('Get items (rows) from a dataset') and immediately delimits scope by saying it returns rows themselves, not metadata, counts, or schema. An agent can distinguish the intent 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?

Gives a clear trigger ('When the user provides a datasetId and asks to retrieve results, output, data, or rows, call this tool directly') plus a usage section and two concrete examples. It lacks explicit when-not guidance relative to any alternative, but the sibling list contains no competing dataset-read 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, so the safety profile is covered elsewhere. The description earns credit for adding behavioral context beyond that: the 'requires the exact key name' precondition and the note that the response preserves the original Content-Encoding, which most clients decompress automatically — a real return-value trait callers would otherwise trip over.

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 key facts — scope, exact-key requirement, encoding caveat — are front-loaded in three tight sentences. The subsequent USAGE and USAGE EXAMPLES blocks are somewhat redundant with the first paragraph, costing a little efficiency.

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?

A two-parameter read tool whose annotations, 100% schema coverage, and output schema already cover safety, inputs, and return shape. The description closes the remaining gap with the Content-Encoding behavior, which is exactly the non-obvious detail an agent needs.

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%, including the keyValueStoreId resolution rules (name vs. username~name) and minLength constraints in the schema itself. The description only reinforces that the key must be exact, adding little semantics beyond what the schema already documents, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the value stored under a specific key in a key-value store') and preemptively scopes it against a listing tool: 'a single record, not a listing of all keys.' An agent can immediately tell this is a point lookup, not an enumeration.

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 says when to use it ('when you need to retrieve a specific record (JSON, text, or binary)') and includes two concrete usage examples showing the store identifier formats. However, it never states when NOT to use it or names an alternative/sibling for enumeration, so the guidance is implied rather than comparative.

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 flag a non-read-only, destructive, open-world operation, and the description adds genuinely useful context beyond them: the cost model ($2 per 1,000 jobs, unsupported companies free). It does not explain the run/wait semantics, but that is covered in the waitSecs schema field, and nothing contradicts 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?

Two sentences, front-loaded with what the tool does, then the capabilities, then the pricing model. No filler and nothing redundant.

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 23 parameters, an output schema, and fully documented schema fields, the description only needs to convey purpose, input forms and cost, which it does. Monitor mode and the many salary/filter interactions are left entirely to the schema, which is acceptable given its 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?

Schema description coverage is 100%, so the baseline is 3. The description echoes a few key concepts (company identifiers as URLs/domains/names, salary as min, max, currency and period, recency filtering) but adds no syntax or behavior beyond what the schema already documents in more detail.

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

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

The description states a specific verb and resource: it calls the named Actor and retrieves its output, and the embedded Actor blurb defines the scope as job postings on Greenhouse, Lever, Ashby, Workable, Recruitee and Teamtailor. That is distinct from the sibling tools (run management, dataset/key-value retrieval), though the link to those siblings is not spelled out.

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 usable input guidance ('paste URLs, domains or names') and use-case framing ('track new job postings', 'filter to jobs posted in the last 24 hours or by minimum salary'), which implies when to reach for it. However, there is no explicit statement of when to use this versus get-dataset-items or get-actor-run, and no preconditions or exclusions.

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