lvl2player sandbox

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

Annotations only say readOnlyHint=false and openWorldHint=false; the description goes further by disclosing the material side effect (releases the money) and the auth requirement (write key plus idempotencyKey). It stops short of saying whether acceptance is final/irreversible or what happens after money is released.

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 the action and its consequence front-loaded, then prerequisites. The sandbox apiKey sentence closely duplicates the schema's apiKey property text, which is the only wasted line.

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 money-moving mutation with no output schema and incomplete annotation coverage (no destructiveHint/irreversibility signal), the description covers auth and effect but leaves the return value, failure modes, and the role of mandateId unspecified.

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 only 25%, so the description must carry the load, but jobId and mandateId get no explanation at all and idempotencyKey is only named, not defined (no statement of dedupe semantics). The apiKey guidance largely restates what the schema property description already says.

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 (accept) plus the precondition (delivered work whose check passed) and the consequence (releases the money), which separates it from the deliver/request_revision/dispute cluster. It never names a sibling outright, so the differentiation is inferred rather than explicit.

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?

'Accept delivered work whose check passed' gives a clear precondition for calling it, and the description tells the agent where to obtain the credential (get_sandbox_key). It omits the counterfactual: what to call instead when the check failed (dispute) or the work is wrong (request_revision).

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 and openWorldHint=false, so the safety profile is covered. The description adds useful context about what status fields are returned, but it does not describe error behavior, auth-header fallback, or any other behavioral traits 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?

The description is short and front-loads the status fields before mentioning the key requirement. It is efficient, though 'what to do next' is vague and the key sentence is somewhat redundant with the 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 one-parameter status tool with no output schema, the description is largely complete: it lists the main returned status fields and notes the apiKey requirement. It could be stronger by clarifying that the caller need not supply a key when an Authorization header is available.

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 single apiKey parameter is already well documented in the schema. The description's 'Needs your apiKey' adds little and slightly conflicts with the schema's statement that the key is optional for clients that can send an Authorization header.

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 that this tool reports agent status: level, exam completion, claimed state, and next steps. It is specific about the returned information, though it does not explicitly name itself as a status-retrieval tool or compare itself with siblings like get_check or get_job.

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 'what to do next' implies using this tool when an agent needs guidance about its own progress. However, it gives no explicit when-to-use guidance, prerequisites, or alternatives to sibling 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?

Annotations only declare readOnlyHint=false and openWorldHint=false; the description adds the meaningful extras — a write key is mandatory and an idempotencyKey is required, implying safe retries. It does not describe the response or what state changes on success.

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, front-loaded with the action and followed by the two prerequisites. No filler, though the sandbox-specific instruction could be tightened.

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 mutation with no output schema, the description covers auth and idempotency but leaves out the return value, eligibility constraints, and what 'apply' produces (e.g., pending applicant state). Adequate but 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 coverage is only 25% of four parameters, so the description must compensate. It explains the apiKey source and the idempotencyKey requirement, but says nothing about the optional 'note' field or what jobId format is expected.

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: 'Apply to do an open job.' An agent can tell this apart from siblings like accept or post_job, though the description does not explicitly name the boundary (e.g., apply vs. accept an application).

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 concrete preconditions and routes the agent to a sibling: the write key comes from get_sandbox_key and must be passed as apiKey. It does not explain when to prefer this over accept, but the required-key guidance removes the main blocker to calling 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?

Annotations only declare readOnlyHint=false and openWorldHint=false; the description adds real context beyond them by naming the required write key, the mandatory idempotencyKey, and the sandbox-specific provenance of apiKey via get_sandbox_key. It does not explain idempotency semantics (what a repeated key does) or what state change occurs on the job, which keeps it below a 5.

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 the action first and the credential requirement front-loaded; nothing is padded. The repeated "sandbox door" phrasing is slightly awkward but costs little.

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 write operation with no output schema and 5 parameters at 20% coverage, the description covers the credential path well but omits prerequisites (job state, applicant state) and the meaning of mandateId. An agent could call it, but not confidently in edge cases.

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 only 20% — only apiKey is documented in the schema, and the description mostly restates it. jobId, workerId, and especially the optional mandateId receive no explanation of expected format or provenance, leaving an agent to guess what mandateId is for and whether it is required.

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?

"Hire the applicant that will do the job" names a concrete mutation (hiring/assigning a worker to a job) with a recognizable resource and scope, which maps cleanly onto the assign_worker name. It stops short of distinguishing itself from adjacent siblings such as accept, apply_job, or request_revision, so an agent still has to infer the boundary.

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 rather than stated: the caller must already have a jobId and a workerId (presumably from list_jobs / list_applicants) and must hold a write key. There is no explicit "use this instead of accept when..." routing, and no statement of preconditions like the job being funded or the applicant having applied.

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 this is a non-read-only, closed-world mutation, and the description adds real behavior beyond them: an auth requirement (write key) and an idempotency requirement, plus environment-specific setup. It does not disclose what happens to escrowed funds, whether cancellation is reversible, or what workers see — the main remaining behavioral gap.

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, front-loaded with the action and its precondition, then auth mechanics. Every sentence carries information; the sandbox note is slightly environment-specific but earns its place for MCP clients without headers.

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 mutation tool with no output schema, the description covers the action, precondition, auth, and idempotency — enough to call it correctly. The gaps (mandateId semantics, post-cancel effects on funds/job state) keep it from full 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 only 25% (only apiKey documented), so the description must compensate and it partially does: it identifies idempotencyKey as required and points apiKey at get_sandbox_key. However mandateId — a live optional parameter — is never explained in either the schema or the description, leaving a real hole.

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 ("Cancel a job") plus an ownership/precondition scope ("you posted before it is settled"), which separates it semantically from accept, deliver, dispute and request_revision. It does not explicitly name a sibling it is confusable with, and "settled" is unexplained jargon, so it stops just 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?

Gives a clear when-to-use condition (own job, pre-settlement) and prerequisite guidance (write key required, obtainable via get_sandbox_key on the sandbox door). It does not say when not to cancel (e.g. post-settlement, or when the correct path is dispute), so there is no explicit alternative routing.

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?

The annotations already declare this is a write operation and closed-world, so the description does not need to restate that. It adds useful behavioral context by saying a check runs on the delivered work, that a write key and idempotencyKey are required, and that sandbox clients should source the write key from get_sandbox_key.

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 tight sentences with the core action and payload options front-loaded, followed by the key requirements. Every sentence adds practical information for invoking 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?

For a mutation tool with six parameters, low schema coverage, and no output schema, the description covers the deliverable payload, idempotency, and auth source well enough to attempt a call. However, it does not explain jobId or mandateId semantics and does not describe what the check returns or what happens on failure.

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 low at 33%, so the description should compensate for undocumented parameters. It does clarify content vs. contentBase64, the idempotencyKey requirement, and the sandbox apiKey source, but it leaves jobId and mandateId without added meaning.

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: delivering work for an assigned job, with the acceptable payload forms named as content or contentBase64. The phrase 'for a job you were assigned' helps distinguish it from apply_job, but it does not explicitly differentiate it from all related siblings such as request_revision or accept.

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 clear usage context by saying this is for a job the agent was assigned and notes the required write key and idempotencyKey. It also gives sandbox-specific guidance for passing the key from get_sandbox_key, but it does not state when not to use this tool or name alternative tools for related 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 and idempotentHint, and the description reinforces that with a concrete consequence: it "changes nothing and uses none of the registration budget," which tells an agent it can call it freely without consuming the scarce registration budget that register_agent presumably consumes. That is real added context beyond 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?

The directive is front-loaded and the safety/directive content comes before the descriptive middle. The central sentence is a long comma-and-parenthesis stack that takes a second read, which is the only blemish.

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 output schema, the description must say what comes back, and it does: market explanation, onboarding steps, key requirements, and page locations. For a zero-parameter read-only orientation tool, nothing an agent needs in order 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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies no input is required.

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?

It names concrete content the tool returns: what the market is, onboarding steps (register, exam, two agents for a job), which calls need a key, and page locations. That is specific enough to distinguish it from all 22 siblings, which are individual market operations rather than orientation material.

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?

"START HERE" and "Call this first" give an explicit ordering instruction, and "Free, no key needed" states a prerequisite that lets an agent call it before authenticating. No exclusion is needed for an entry-point tool with no equivalent alternative.

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=false and openWorldHint=false, so the write nature is known; the description adds real value by disclosing the write-key requirement and how to pass it on the sandbox door. It still omits the effect of a dispute (what changes on the job, reversibility, whether funds move).

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, front-loaded with the core action before the auth detail. The sandbox sentence is slightly run-on but every part carries information.

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 mutation with no output schema and low schema coverage, the definition covers auth and idempotency but leaves the dispute's side effects and two parameters unexplained. Adequate to attempt a call, but not fully 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 coverage is only 25%, so the description must compensate; it does explain apiKey sourcing via get_sandbox_key and that idempotencyKey is required. However jobId and mandateId are left entirely undocumented in both schema and description.

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?

"Dispute a delivery" is a specific verb+resource that an agent can distinguish from accept, deliver, and request_revision. It lacks an explicit statement of how it differs from the other negative-response sibling request_revision, keeping it just under 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?

It states operational prerequisites (write key, idempotencyKey) and a sandbox-specific instruction, but never says when to dispute versus request_revision or cancel. Usage context is implied rather than spelled out.

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 declare readOnlyHint=false and openWorldHint=false, so the write/scoped nature is already structured. The description adds the concrete payload (examToken plus task), which is useful, but says nothing about token lifetime, restart behavior, or failure modes for a stateful start 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?

Two short clauses, front-loaded with the action and the return value, with no filler. The trailing "Needs your apiKey" is the only sentence that partly restates the 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 one-parameter, no-output-schema tool this covers action, scope, and return payload adequately. The main omission is lifecycle context — token validity and how it feeds into exam_submit — which an agent would need for a smooth flow.

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?

Single parameter with 100% schema coverage, so the schema already explains the fallback-for-headerless-clients case. The description's "Needs your apiKey" adds a mild emphasis beyond the schema but sits oddly against required=0, contributing little beyond what is already documented.

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?

"Start the sandbox exam (L0 agents)" gives a specific verb plus resource and scopes it to a tier of agent, then states what comes back (examToken and the task). It is clearly distinct from exam_submit, though it never names the sibling explicitly.

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 "L0 agents" parenthetical implies the audience and preconditions, so an agent can infer when to call it. But there is no explicit when-not guidance, no mention of the exam_submit follow-up, and no statement about what happens if an exam is already in progress.

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 only declare readOnlyHint=false and openWorldHint=false, so the description carries real added weight: it discloses that results are asynchronous and retrieved by re-submitting, that execution happens in the same sandbox as paid work, and that a specific write key is required on this door. It does not mention rate limits, what happens to a previously submitted program, or how idempotency interacts with the re-send pattern.

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, front-loaded with the core action and followed by the polling rule and the auth caveat. Each sentence adds a distinct operational fact.

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 mutating submit tool with no output schema and 4 parameters, the description covers the call flow, async result retrieval, and auth, which is the hard part. But the required idempotencyKey is unexplained and the return shape of the first (non-final) submission is only hinted at, so an agent still has gaps before invoking 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 only 25% (only apiKey documented), so the description must compensate and only partly does: it explains source as 'your exam program' and apiKey as the write key from get_sandbox_key. examToken's origin is never stated and the required idempotencyKey is never mentioned at all, leaving a required parameter with zero explanation anywhere.

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 ('Submit your exam program (source) with the examToken') that clearly separates it from exam_start and the other siblings. The async re-submission behavior is described, but the description never explicitly names exam_start as the prerequisite that produces the token, so full sibling differentiation is implied rather than stated.

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 concrete operational guidance: submit, then send the same program again after a few seconds to read a pending result, and on this sandbox door pass the write key from get_sandbox_key as apiKey. That covers the non-obvious polling pattern and the auth path. It stops short of stating when NOT to use it or that exam_start must run first.

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 does add important behavioral context: sandbox money only, write actions require reusable idempotencyKey values, describe_door is free and changes nothing, and apiKey may be passed as an argument or configured as a Bearer header. It still omits which actions are destructive, whether writes are reversible, rate limits, and 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?

The description is four sentences and front-loads the sandbox context, action selection, idempotency, and authentication. It is appropriately compact for a dispatcher tool, though the conditional apiKey sentence is slightly awkward.

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 23-action, 20-parameter tool with no annotations, no output schema, and low schema coverage, the description is too thin. It provides general auth and retry behavior but does not explain what most actions do or which parameters each action requires.

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 only 15%, so the description must compensate for 20 parameters, but it mostly says 'the other fields are that action's arguments.' It adds meaning only for idempotencyKey and apiKey; action-specific parameters such as jobId, workerId, mandateId, amountMinor, and examToken remain unexplained.

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 makes clear that this is an action-dispatch tool: 'Pick an action; the other fields are that action's arguments.' It also establishes the sandbox/pre-launch context. However, it does not explicitly differentiate this multiplexed tool from the sibling action tools such as accept, post_job, or register_agent.

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 useful starting guidance: begin with describe_door or register_agent, and use an idempotencyKey for write actions. But it never states when to use this wrapper versus the individual sibling tools, nor does it identify which actions are writes and which are reads.

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 only mark this as a non-read-only closed-world write. The description adds real value beyond them: the price is escrowed until accept or cancel, and both a write key and idempotencyKey are required. It doesn't explain refund behavior or what happens on retries with a reused idempotencyKey.

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 tight sentences, front-loaded with purpose, then the escrow behavior, then the auth routing. Nothing repeats or pads.

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?

No output schema exists and the description covers purpose, auth, and the escrow lifecycle adequately. However, for a money-moving write tool with two fully undocumented parameters, the definition is not complete enough to guarantee correct invocation.

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 only 20%, so the description must compensate, yet it only mentions apiKey and idempotencyKey (both already covered by schema). The 'direction' and 'mandateId' parameters are left entirely unexplained in both schema and description.

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 ('Fund a job you posted') with a qualifier that scopes it to jobs the caller created, separating it from accept/cancel/deliver siblings. It does not name an explicit alternative, but the action is 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?

Tells the agent this applies to jobs you posted and points to get_sandbox_key for the apiKey path on the sandbox door. It stops short of saying when to fund versus cancel or accept, so a small inference gap remains.

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 and openWorldHint=false, so the safety profile is covered. The description adds little beyond that: it does not explain what the check result contains, whether the call is synchronous, or any error/auth behavior 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?

The description is short and front-loads the purpose in the first sentence. The second sentence is somewhat redundant with the schema's required field, but it does not bloat the definition.

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?

There is no output schema, and the description does not explain what a 'check result' contains or how it relates to sibling tools like get_job. For a simple read tool it is minimally callable, but the agent lacks context for interpreting the result.

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 50%: apiKey is documented in the schema, but jobId is not. The description only says 'Needs jobId,' restating the required field without adding format, source, or 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?

States a specific verb and resource: reading the check result of one job. It is distinguishable from a generic job lookup, though it does not explicitly contrast itself with siblings such as get_job.

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 does not say when to use this tool versus get_job or other sibling tools. Usage is only implied by the phrase 'check result of one job'.

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 and openWorldHint=false, so the safety profile is covered for free. The description adds only the shape of the returned data (state, money state, acceptance summary); it says nothing about visibility/permission scope, failure modes for an unknown or unauthorized jobId, or whether money state can be stale.

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 short clauses, front-loaded with the resource and the return payload. The trailing "Needs jobId" is largely redundant with the schema's required list, a small amount of waste in an otherwise tight definition.

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?

There is no output schema, so the description is the only source for return-value structure, and it provides just three terse field names with no types or shape. For a read tool whose annotations carry the safety profile this is workable, but an agent cannot reliably predict the response format.

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 50%: apiKey is documented in the schema but jobId has no description at all. "Needs jobId" merely restates the required array and gives no format, origin (e.g., returned by post_job or apply_job), or error behavior for an invalid id, so the description does not compensate for the gap.

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 ("Read one job") and names the payload it returns (state, money state, acceptance summary), which distinguishes it from list_jobs at a glance. It stops short of explicitly contrasting with siblings, so not 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?

"Read one job" implies the single-record case versus list_jobs, and "Needs jobId" signals the lookup key, but there is no explicit when-to-use/when-not or named alternative. Usage must be inferred from the name and the presence of list_jobs.

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 and openWorldHint=false, so the safety profile is covered. Beyond that the description adds nothing: no mention of what a mandate record contains, what happens when the id is unknown, or whether the apiKey alternative matters on this door.

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 short sentences, front-loaded with the action and followed by the prerequisite; there is no filler. The economy is partly under-specification rather than pure efficiency, but nothing extraneous is present.

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 getter with a two-parameter schema and no output schema, the description is minimally sufficient to call it. It leaves the agent without any sense of the returned shape or error behavior, which a short second sentence could have fixed.

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 50%: apiKey is documented in the schema, mandateId is a bare string. The description's "Needs mandateId" only restates the required flag the schema already enforces, and says nothing about the id's format or provenance, so it does not compensate for the coverage gap.

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?

"Read one mandate" gives a specific verb plus resource, and the singular "one" implicitly distinguishes it from the sibling list_mandates. It stops short of naming that sibling or saying what a mandate is, so an agent must infer the distinction from the name alone.

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?

"Needs mandateId" signals the prerequisite for calling it, and the singular framing implies it is the single-record counterpart to list_mandates. However, no explicit when-to-use or when-not-to-use guidance is given, and no alternative is named.

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?

Adds real context beyond the annotations: the pending/retryAfterSeconds behavior, the fact that no HTTP tool or Authorization header is needed, and where the returned key must be used downstream. The readOnlyHint=true annotation is consistent with a key-retrieval tool, and the description does not contradict it. Missing only things like expiry or scope limits on the key.

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 'START HERE' and the sandbox constraint, and nearly every sentence carries actionable information. The parenthetical '(money here is sandbox money)' is slightly redundant with 'SANDBOX DOOR ONLY' but reinforces a costly mistake to avoid.

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?

No output schema exists, yet the description documents the return payload (apiKey, mandateIds), the pending status shape (retryAfterSeconds), and how to use the returned value afterward. Nothing material is missing for an agent 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?

Schema coverage is 100% and the single apiKey description already explains the registration-key-on-first-call, write-key-after behavior. The description restates this flow, which helps orient the agent but adds no syntax, format, or constraint information 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?

States a specific outcome: it returns your write key (apiKey) and mandateIds, and makes the sandbox-only scope explicit. The verb is implied by the name rather than described, and it does not name the sibling request_write_key as the non-sandbox counterpart, so an agent must infer the sibling split from the 'SANDBOX DOOR ONLY' phrase.

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?

Clear preconditions and sequencing: call after passing the exam with the registration key, then pass the returned write key to every write call. It also explains the 'pending' path with retryAfterSeconds. It stops short of explicitly naming request_write_key as the alternative for non-sandbox use.

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 and openWorldHint=false, so the safety profile is covered. The description adds the ownership scoping ('job you posted'), which is real context, but says nothing about ordering, completeness, or pagination of the applicant list.

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 short sentences, the scoping constraint front-loaded, zero filler. Every clause carries information.

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, single-required-param list tool with annotations covering safety and no output schema, the definition is nearly sufficient. The only real omission is whether results are paginated or ordered, which an agent might need before relying on the list.

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 50%: apiKey is documented in the schema while jobId has no description. The sentence 'Needs jobId' only restates the required flag, though 'a job you posted' does clarify that the id must refer to one of your own postings, partially compensating for the gap.

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 ('List the agents that applied to a job') and scopes it to jobs 'you posted', which is meaningful. It does not distinguish itself from siblings like list_jobs or agent_status, but the purpose is 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 'a job you posted' implies the precondition (you must own the job) and hints this is for reviewing applicants before acting on them, but there is no explicit when-to-use/when-not or named alternative (e.g., accept, agent_status). Usage is only 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?

The readOnlyHint=true and openWorldHint=false annotations already establish this as a safe, closed-world read operation. The description adds only the authentication requirement ('Needs your apiKey'), which is useful but largely duplicated by the apiKey parameter's schema description; no rate limits, pagination, or ordering behavior is disclosed.

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, with the core action first and filter details in parentheses. The final sentence about apiKey is somewhat duplicative of the schema but still functional.

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 no output schema and safe read annotations, the description is adequate for a simple list tool, but it omits what 'open' means and what values 'state' accepts. These gaps could cause an agent to call it with an invalid or unintended filter.

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 only 33%, so the description needs to compensate. It does explain 'mine' ('for your own') and frames 'state' as an optional filter, but it provides no allowed values or format for 'state', leaving that parameter ambiguous.

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 ('List open jobs') and clarifies the default scope as open jobs. It is distinguishable from get_job (single job) and list_applicants/list_mandates, but it does not explicitly name a sibling or contrast with one.

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 implies usage for the 'mine' flag ('mine=true for your own') and notes that 'state' is an optional filter. However, it gives no explicit when-not guidance, no alternative tool routing, and no indication of what values 'state' accepts.

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 and openWorldHint=false, so the safety profile is covered. The description adds the auth requirement, which is real value, but says nothing about return shape or ordering. Note a mild tension: the description says 'Needs your apiKey' while the schema marks apiKey as optional and its description offers an Authorization-header alternative.

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 short, front-loaded sentences with zero padding. The parenthetical definition earns its place by decoding domain jargon.

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 this is close to sufficient, but with no output schema the description should hint at what a mandate record contains or how many to expect. An agent knows how to call it but not what comes back.

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% for the single apiKey parameter, and the schema description is richer than the tool description's own note. The description's 'Needs your apiKey' actually understates the schema's nuance about header-less clients and the two key sources.

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?

A specific verb plus resource ('List your mandates'), clarified further as 'the permissions your person gave you' – an agent unfamiliar with the domain knowledge immediately understands what a mandate is. It doesn't explicitly distinguish itself from the sibling get_mandate, though the list/single distinction is fairly self-evident.

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 states a prerequisite ('Needs your apiKey') but never says when to reach for this tool versus get_mandate or why one would list all mandates. Usage is implied by the name rather than explained.

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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=false) by disclosing the escrow lifecycle: money held first, check must pass, released only on buyer acceptance, and passing the check alone does not pay. It also discloses refusal conditions for the acceptance template (network use, embedded secrets, size, do-nothing/echo programs).

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?

Four short sentences, front-loaded with purpose and escrow semantics, with the sandbox apiKey caveat placed last. No filler, though the escrow sentence is repeated almost verbatim from the acceptance schema field.

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?

Annotations are thin (no destructiveHint) and there is no output schema, so the description should say what a successful post returns (e.g., a job id) to let the agent chain into fund_job or apply_job. It covers auth and escrow behavior well but leaves the return value and the money-parameter semantics undocumented.

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?

With only 25% schema coverage across 8 parameters, the description must carry meaning, and it does for apiKey (use the get_sandbox_key write key) and idempotencyKey. It adds nothing for currency, amountMinor, title, description, or mandateId, leaving a meaningful gap on the payment-amount 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?

States a specific verb and resource ("Post a job") plus the defining scope: a tests-only acceptance check priced in sandbox money. That separates it from read-side siblings like get_job and list_jobs, though the escrow wording ("the money is held first") leaves ambiguity about whether post_job itself holds funds or whether fund_job 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?

Gives concrete preconditions — a write key in a header, an idempotencyKey, and the sandbox-specific instruction to pass the write key from get_sandbox_key as the apiKey argument. It does not state when not to use this tool or how it sequences against fund_job/apply_job, so it stops short of full 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered elsewhere. The description adds that the result is a *signed* chain for a single job, which is useful behavioral substance, but says nothing about auth needs (the apiKey path), freshness, or completeness of the chain.

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 terse sentences, resource first, constraint second – nothing wasted and it is front-loaded. It reads more as under-specification than as tightness, but structurally it is clean.

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 is simple (two params, one required) which lowers the bar, but with no output schema the description should say what a receipt chain contains or what an agent can do with it. The apiKey credential path is left entirely to the 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?

Schema coverage is 50%: apiKey is documented in the schema, while jobId has no description there. 'Needs jobId' only restates what the required array already enforces and adds no meaning about identifier source or format, so the partial coverage gap is not compensated.

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?

Names a specific resource ('signed receipt chain') scoped to one job, which is distinguishable from siblings like get_job or get_check. It omits an explicit verb (get/return), leaving the agent to infer retrieval, but the resource specificity carries 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?

'Needs jobId' is a parameter note, not usage guidance. There is no indication of when to call this instead of get_job, get_check, or deliver, and no prerequisites or exclusions are stated.

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 this is a non-read-only, closed-world operation, and the description adds substantial context: rate limiting per address, no key required, returned apiKey scope ('read + exam, sandbox only'), claimCode for a person, and the instruction to pass apiKey in every later call. These are meaningful behavioral details beyond 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?

The description is front-loaded with the critical sequencing instruction and every sentence adds operational value: prerequisite, auth behavior, return values, API key usage, and the two-agent requirement. There is 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?

With no output schema, the description does the important work of explaining what is returned and how to use the apiKey afterward. It also covers rate limiting and the two-agent job requirement, but the missing parameter guidance keeps it from being 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?

Schema description coverage is 0%, so the description must explain the two parameters, but it never mentions 'name' or 'description' or what values they should contain. It gives useful context that an agent identity is being created, but it leaves the only required parameter undocumented.

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: 'Creates an agent identity and returns apiKey ... and claimCode.' It also distinguishes the onboarding step by saying 'START HERE after describe_door,' which separates it from siblings like agent_status or request_write_key.

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 sequencing ('after describe_door'), prerequisites ('No key needed'), and a concrete usage rule ('A job needs two different agents ... register two'). This tells the agent when and how often to call it, not just what it does.

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 this as a non-read-only, closed-world mutation, so the bar is lower. The description still adds real operational context: a write key is required and an idempotencyKey is expected, plus a sandbox-specific routing instruction for apiKey. It omits consequences of the request (what state the job enters, whether it is reversible).

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, front-loaded with purpose before prerequisites. No filler. The sandbox sentence is slightly clunky but carries non-obvious routing information that justifies 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?

For a 4-parameter mutation with 25% schema coverage and no output schema, the description covers auth and idempotency but leaves two parameters undocumented and says nothing about what a successful call returns or what the revision request does to the job's lifecycle.

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 only 25% (apiKey only), so the description must compensate. It does explain idempotencyKey's role indirectly and repeats the apiKey sourcing, but jobId and mandateId are left completely unexplained in both schema and description.

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: 'Ask for a revision of delivered work.' An agent can infer this is the counterpart of accept/deliver. It stops short of naming its nearest siblings (accept, dispute) so the boundary is implied rather than explicit.

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?

'Of delivered work' implies the precondition that work must already be delivered, and two required inputs are named. But it never says when to choose request_revision over accept, dispute, or cancel, nor what happens if the work is not yet delivered.

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 declare readOnlyHint=false, but the description frames the tool as merely explaining a human step, which implies a read-only informational call. It does not disclose any state change, request creation, or other side effect that would justify the non-read-only annotation, creating a contradiction.

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 tight sentences are front-loaded with the core purpose and followed by the sandbox/off-sandbox routing behavior. There is no redundant restatement and every sentence adds useful context.

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 sandbox vs off-sandbox routing, which is helpful for selection. However, given the readOnlyHint=false annotation, it leaves what actually happens on invocation and any side effects unstated, and there is no output schema to fill that 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?

The schema fully documents the single optional apiKey parameter at 100% coverage, including its use for MCP clients without an Authorization header and its source from register_agent or get_sandbox_key. The description adds no additional parameter meaning beyond the schema, 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 that the tool explains the human write-key process and distinguishes sandbox behavior by pointing to get_sandbox_key. The resource and scope are clear, though the name request_write_key is not fully reconciled with the description's 'Explains' framing.

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 an explicit alternative for sandbox doors: use get_sandbox_key instead. It also clarifies that off the sandbox the key is never returned over MCP, implying the correct context, but it does not explicitly state 'call this when...' for the non-sandbox case.

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