Octopus

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

With no annotations, the description carries the full disclosure burden. It states the core mutation: budget release and task completion, and adds a critical precaution to verify before calling. It does not mention irreversibility or output/error behavior, but the primary consequences are 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?

Two sentences, no filler. The main effect is front-loaded in the first sentence, and the essential verification warning is placed in the second. Every word earns its place.

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

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

For a simple three-parameter tool with no output schema, the description conveys purpose, effect, and a required pre-check. It doesn't describe return values or error cases, but the agent has enough to invoke it correctly and understand the consequence.

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 67%, covering api_key and feedback. The description adds no parameter-specific meaning beyond the schema; it mentions verifying criterion responses and attachment URLs, which relates to task content rather than any parameter's format or usage. This is a fair baseline for a mostly documented schema.

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

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

The description uses a specific verb ('Accept') and names the precise effect: 'releases the escrowed budget to the human and completes the task.' This clearly identifies the tool's role and distinguishes it from siblings like octopus_request_changes and octopus_cancel_task.

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

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

It gives clear context for when to use the tool: after submitted work is accepted, and it explicitly instructs the agent to 'Verify each criterion response (and open attachment URLs) first.' It does not explicitly contrast with alternatives such as requesting changes or canceling, so it stops 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?

With no annotations present, the description carries the full burden of behavioral disclosure. It does disclose a meaningful consequence ('full refund') and the allowed task statesmaisn. However, it does not state whether cancellation is irreversible, how refunds are returned, or what happens to claims on the task. This is adequate but leaves significant behaviors implicit for a destructive financial action.

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

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

The description is two short sentences, with the core operation front-loaded and the eligibility conditions immediately after. Every word contributes value; there is no redundancy or filler.

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

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

For a simple two-parameter tool, the essential inputs and eligibility are covered. However, the absence of an output schema and annotations means the agent is not told what happens after a successful cancellation, how errors surface when a task is not cancellable, or any side effects beyond the refund. It is usable, but not 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 coverage is 50%: api_key is well documented in the schema, while task_id has only a type with no description. The description does not explicitly explain task_id, though 'Cancel a task' makes its role fairly obvious. The description adds little parameter meaning beyond the schema, but the lack of detail on task_id is partially mitigated by the tool's clear purpose.

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 very specific verb and resource ('Cancel a task') and adds a key consequence ('for a full refund'). The state restriction ('Allowed while open, or while claimed-and-overdue') further differentiates this from sibling operations like approve, request_changes, or post_task, making it unmistakably the cancellation tool.

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 conditions for when cancellation is permitted ('Allowed while open, or while claimed-and-overdue'), which tells an agent when this tool is appropriate. It does not explicitly name alternatives or state 'use X instead', but the allowed-state wording effectively excludes use in other situations.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains what pre-registering does (recruit workers, priority access, $10 fee credit) but does not disclose the response shape, idempotency, or whether registering costs anything. This is adequate but leaves gaps.

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

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

The description is two sentences with no filler. The action and scope are front-loaded, and the incentive details are useful rather than 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?

Given the nested array parameter, lack of output schema, and no annotations, the description could do more. It covers why and when to use the tool but omits success/failure behavior and the concrete effect of a declaration, which an agent may need to verify a call succeeded.

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 50%, so the description needs to compensate. It does name the key fields (category, description, locations, cadence), which adds context beyond the bare schema, but it does not explain formats, requiredness semantics, or how intents map to later task posting.

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 ('Pre-register') and a resource ('the kinds of tasks you expect to post'), and enumerates the fields involved (category, description, locations, cadence). This clearly distinguishes it from siblings like octopus_post_task and octopus_marketplace without needing to open 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?

The description communicates clear context: use this before posting recurring task categories to get worker recruitment and priority access. It does not explicitly name alternatives or state when not to use it, but the pre-registration framing makes the intended timing clear.

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

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

With no annotations, the description carries the behavioral burden and does so well: it discloses long-polling behavior, the 55-second maximum wait, and the incremental sync semantics of since_* fields. The read-only nature is implied by 'Fetch' and the descriptive return fields, though it does not cover timeout behavior or explicitly guarantee no side effects.

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

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

The description is two sentences with no filler: the first sentence states the resource and return fields, and the second packs in the parameter behavior. All information is front-loaded and earns its place.

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

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

Given that there is no output schema and no annotations, the description covers the main return fields and all non-obvious parameters well. It is missing explicit timeout/error behavior and precise since_status value formats, which would make it fully self-contained.

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% (api_key is documented), and the description compensates by explaining wait_seconds, since_status, and since_messages in meaningful, actionable terms. task_id is left implicit as the obvious required identifier, and the exact format of since_status is not specified, so it is not a perfect 5.

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

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

The description opens with a specific verb and object ('Fetch one of your tasks') and enumerates the expected payload: status, submissions with per-criterion evidence and attachment URLs, message thread, and an advice field. The 'one of your tasks' phrasing differentiates it from the listing sibling octopus_my_tasks and from mutation tools like octopus_approve or octopus_cancel_task.

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

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

It gives clear operational guidance: use wait_seconds to block until the status moves or a new message arrives, and pass since_status/since_messages from the last look for incremental polling. It does not explicitly name when not to use the tool or contrast it with siblings, so it stops 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?

With no annotations, the description carries the burden of behavioral disclosure. It helpfully states that no authentication is needed and that data is 'live', implying real-time retrieval. However, it does not explicitly say this is read-only, nor does it describe the output format, pagination, or any rate limits. This is adequate for a zero-parameter public data tool but not fully transparent.

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

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

The description is extremely concise: one short sentence plus an auth note. It front-loads the resource and gives essential context without filler. Every word adds value.

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 zero-parameter tool with no output schema, the description covers the essential facts: what it provides ('stats and recent open tasks') and that no auth is needed. While it doesn't specify the exact return structure, an agent can safely invoke it and inspect results. Given the tool's simplicity, the description is nearly complete.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly omits parameter information and instead hints at what the tool returns, which is sufficient given no parameters exist to document.

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 the resource ('marketplace stats and recent open tasks') and qualifies it as 'live', which implies a read/retrieval tool. It distinguishes itself from sibling action tools like octopus_post_task and octopus_approve by focusing on public marketplace data rather than user-specific actions. However, it lacks an explicit verb like 'get' or 'list', and 'stats' is somewhat vague.

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

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

No guidance is provided on when to use this tool versus siblings. It does not mention that this is the tool to browse open tasks before applying or that octopus_my_tasks would show user-specific tasks. The only contextual hint is 'No auth needed', which is a prerequisite rather than a usage condition.

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

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

No annotations are provided, so the description carries the burden. It discloses that the tool returns statuses and that 'submitted' tasks need review, which is useful behavioral context. However, it doesn't mention pagination, ordering, or whether the list is limited to open tasks vs all historical tasks.

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

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

Two sentences, front-loaded with the core purpose, and the second sentence adds actionable guidance. No wasted words.

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

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

For a simple list tool with no required parameters and full schema coverage, the description is nearly complete. It could mention whether the list is paginated or sorted, but the core usage and the key status meaning are covered.

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 schema already documents both parameters. The description adds the meaning of the 'submitted' status in the context of the returned list, which is helpful, but doesn't add detail about the status filter beyond what the schema provides.

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

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

The description clearly states the tool lists tasks the user has posted, with statuses, and distinguishes it from the broader marketplace listing tool. The verb 'List' plus the resource 'tasks you have posted' is specific and unambiguous.

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

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

The description gives clear context for when to use it (to see your own posted tasks) and even highlights a key action trigger: tasks with status 'submitted' need review. It doesn't explicitly name alternatives, but the sibling list makes the distinction clear enough.

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

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

With no annotations, the description carries the full burden. It discloses the financial mechanics (budget escrowed, 15% fee, release on approval), the time scale, and that humans answer criteria with evidence. It does not mention rate limits or return value, but covers the critical behavioral aspects for a posting tool.

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

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

The description is a single dense paragraph, front-loaded with the core purpose, then details about budget, criteria, and timing. Every sentence adds new information – no fluff. It is efficiently structured for an agent to parse quickly.

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 8 parameters, no output schema, and no annotations, the description covers purpose, process, costs, and timing. It lacks an explicit statement of the return value (e.g., task ID) needed for later polling, but that is a minor gap given the overall 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 coverage is 75% (7/8 params described). The description adds value beyond schema by explaining budget semantics (entirely to worker, fee structure) and giving guidance on criteria format, which complements the parameter descriptions. It doesn't repeat schema details but adds context.

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

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

The description opens with 'Hire a human: post a paid task to Octopus' – a specific verb and resource. It clearly distinguishes this from siblings like octopus_get_task (poll) and octopus_marketplace (browse), and explains the purpose is to outsource work to a human.

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?

Explicitly instructs 'post early, keep working, then poll with octopus_get_task', naming the alternative tool and timing. Also explains when the fee is waived and advises writing criteria as verifiable checks, giving an agent clear context on how to use this tool effectively.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It reveals the account creation, returns an api_key, mentions beta fee waiver and credit, but does not mention any authentication or persistence requirements beyond saving the key. It could be more transparent about what happens if the key is lost or if the account already exists.

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 action and its result, but it includes a marketing note about beta credits that is not essential for tool invocation. It could be trimmed to focus on operational steps, but overall it's efficient.

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

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

The description covers the essential outcome (api_key), the single-use rule, and the optional intents pre-registration, which is sufficient given the rich schema. The main gap is not detailing edge cases like error handling or idempotency, but for a simple creation tool this is adequate.

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

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

Given the schema has 100% coverage, the baseline is 3, but the description adds significant value by explicitly warning 'SAVE IT somewhere durable: .env, project memory' for the api_key, and by explaining the intents parameter's benefits (recruitment, priority access, fee credit) that go beyond the schema's generic 'Recommended' note. This greatly enhances semantic understanding.

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 'Create an Octopus agent account' with a specific verb and resource, and distinguishes itself from siblings by indicating this is a one-time setup action. The instant return of an api_key adds clarity about its primary function.

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

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

The description advises 'Do this once per project, not per session,' which implies when to use it, but it does not explicitly contrast with alternatives like octopus_declare_intents for pre-registering demand. It provides good usage context but no explicit 'when not to use' 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It states that the tool sends work back for revision and that the human will revise and resubmit, implying a collaborative workflow. However, it does not disclose whether the tool requires specific permissions, whether the action is reversible, or what happens if the task is not in a submittable state. The mention of 'specific, per-criterion feedback' adds some detail, but more transparency is needed for a full understanding.

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

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

The description is concise (a single sentence plus a short clause) and front-loads the main action. It wastes no words and is easily parseable. The only minor issue is that it could have included a bit more detail on usage without bloating, but as is it is efficient.

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's moderate complexity (3 params, 2 required) and no output schema, the description is somewhat minimal. It explains the tool's purpose and the response behavior (human revises and resubmits), but it does not cover important aspects like error conditions, idempotency, or the meaning of the 'task_id' parameter. The lack of annotations and output schema raises the burden on the description, and it falls short of 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 33%, meaning only api_key is described in the schema. The description clarifies the purpose of 'feedback' (specific, per-criterion feedback) which adds context beyond the schema, but 'task_id' is left as a bare string. The description partially compensates for the low coverage but does not fully explain the format or expected content of the 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?

The description clearly states the verb ('Send back for revision') and the resource ('submitted work'), and specifies the action type (request changes) with a clear outcome ('The human revises and resubmits'). It distinguishes itself from sibling tools like octopus_approve (which would be the opposite action) by implying this is the rejection/revision counterpart, though it does not explicitly name the sibling.

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

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

The description gives a clear context of when to use it: when submitted work needs revision. However, it does not provide explicit 'when not to use' or name alternative tools such as octopus_approve for approval or octopus_send_message for general communication. The guidance is adequate but could be more explicit about exclusions.

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

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

With no annotations present, the description carries the burden of behavioral disclosure. It communicates that this is an interactive reply action and implies a human-in-the-loop dependency, but it does not describe side effects, authentication behavior, rate limits, or what happens after sending.

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

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

The description is a single, tightly front-loaded sentence that names the action first and adds purpose plus urgency without fluff. Every clause earns its place.

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

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

For a simple message-sending tool with no output schema and no annotations, the description covers the essential action, when to use it, and why timeliness matters. It could add more detail about response format or failure behavior, but the core context an agent needs is present.

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 low at 33%, so the description must compensate. It does reasonably well: 'reply on a task's thread' conveys that task_id identifies the task, and 'answer' clarifies that body is the reply content. It does not provide formatting details or examples, but the core meaning of both required parameters is inferable.

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

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

The description clearly identifies the action as replying on a task's thread, which is a specific verb and resource. It also provides context about clarifying questions, which helps distinguish it from sibling tools like octopus_approve or octopus_request_changes, though it does not explicitly name an alternative.

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

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

The description gives clear context for when to use the tool: when the human working the task asks clarifying questions. It adds an urgency guideline ('answer promptly or the work stalls'), but it does not explicitly say when not to use it or mention alternatives.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses the primary output (Stripe Checkout URL) and the sandbox override, but does not mention potential side effects (e.g., does it create a pending charge?), idempotency, or error handling. The information provided is useful but incomplete for a payment tool.

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

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

Two sentences with no filler. The main purpose is front-loaded, and the sandbox caveat is appended concisely. Every word earns its place.

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

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

For a simple two-parameter tool with no output schema, the description covers the return value and sandbox behavior. It does not mention failure modes, idempotency, or whether the payment link expires, but these are likely not critical for basic usage. Overall, it is adequately complete for the tool's complexity.

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

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

Schema description coverage is 50% (api_key has a description, amount_usd does not). The tool description adds no parameter-specific details. amount_usd is self-explanatory as a dollar amount, and api_key's schema description already covers authentication. Baseline 3 is appropriate since the description does not compensate for the missing amount_usd description but does not need to.

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 'Create' with a clear resource 'a payment link to add credits' and explicitly states the return type (Stripe Checkout URL). It is distinct from all sibling tools, none of which handle top-ups, so an agent can easily identify its purpose.

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 context is clear: use when you need to add credits via a payment link. It also notes sandbox-mode behavior. However, it does not explicitly state when not to use or mention alternatives, though none exist among siblings, so this is a minor gap.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It never explicitly states that this is a read-only operation, what the tool returns, or whether it has side effects. The phrasing 'Your credit balance and ledger' implies retrieval, but an agent is left to infer the safety profile.

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

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

The description is two short sentences with no wasted words. The core resource is stated first, and the relevant sibling routing follows immediately. It is highly scannable for an agent.

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

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

For a tool with zero required parameters, a single optional parameter, and no output schema, the description is nearly complete. It names the resource and points the agent to the correct sibling for a mutating alternative. The main gap is that the return shape and read-only nature are implied rather than stated.

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 api_key parameter is already fully described with its prefix and optional Bearer-header fallback. The description adds no parameter-specific meaning beyond the schema. This matches the baseline for well-covered schema 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?

The description identifies the resource precisely: the agent's credit balance and ledger. It doesn't use an explicit verb like 'get' or 'view', but the noun phrase clearly conveys what the tool exposes internally. It also differentiates from the sibling octopus_topup by routing credit-adding behavior away.

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

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

The description gives an explicit alternative for a related action: 'To add credits: octopus_topup.' This helps an agent choose between wallet and topup. It doesn't enumerate all non-uses, but for a simple balance tool the relevant exclusions are mostly covered.

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