AANet

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

There are no annotations, so the description carries the full behavioral burden. It discloses the success return shape, the 409 conflict case, that a lost race is free, that leases expire after lease_seconds, that the other agent can quote acquire it out from under you quote, and that locking is not permanent. This is comprehensive behavioral disclosure for a locking 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?

Every sentence has a distinct purpose: it states the tool's job, gives a critical timing rule, explains the lease expiry consequence, and then directs renewal and release behavior. It is information-dense but not bloated, and the most important instruction is front-loaded.

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 complexity, the absence of annotations, and the absence of an output schema, the description is strikingly complete. It tells the agent what happens on success, what happens on conflict, who can take the lock, when the lock can be lost, and what to call next. No critical piece of operational knowledge is missing.

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

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

Schema coverage is 100%, so the description does not need to re-document every parameter, but it adds meaningful semantics: name is a unit of work and lease_seconds controls the duration before the lock becomes reclaimable. This is value the schema does not express in terms of the locking protocol, though it does not add much beyond that.

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 begins with a specific verb and resource: 'Claim exclusive ownership of a named unit of work'. It also states the exact purpose — preventing another sub-agent from starting the same work — and the sibling names make the distinction from aanet_renew_lock and aanet_release_lock clear even without explicitly naming them. This removes all ambiguity about the tool's role.

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 explicitly says 'call this before starting work, not after', and then provides a complete usage protocol: renew periodically with aanet_renew_lock and release with aanet_release_lock when done. It tells the agent not only when to use this tool but when to use related siblings and why, which is exactly the guidance needed.

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 and discloses key behaviors: append semantics (doesn't touch existing), creation on missing file, a side effect (fires file_write webhook), and the return shape. It could mention authentication requirements or conflict behavior, but the schema covers api_key and if_match. This is solid transparency.

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 zero waste: the primary behavior is front-loaded, followed by the alternative, a use case, a side effect, and the return value. Every sentence earns its place and the structure is optimal for quick comprehension.

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 a rich schema and no output schema, the description is nearly complete: it covers behavior, alternatives, side effects, and return shape. It doesn't explicitly state error conditions or auth prerequisites, but the schema covers api_key, and the use case is clear. Nothing critical is missing for 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 100%, so the schema already documents all five parameters thoroughly. The description adds minimal parameter insight beyond stating 'append as a new entry', which matches the content parameter. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('Append one entry to a file') with explicit constraints (doesn't touch existing content, creates if missing) and distinguishes itself from aanet_write_file by naming the alternative. This makes the tool's purpose unambiguous and differentiates it from sibling tools.

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 explicitly tells the agent when to use this tool versus aanet_write_file ('use aanet_write_file instead when you need to replace the whole file') and provides a typical use case (shared log or running notes). This is clear, actionable guidance with an alternative 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?

No annotations are provided, so the description fully carries the burden. It discloses key behaviors: no payment, pre-funded with 1000 units, expiry after one hour, permanent deletion, rejection of deposit/refund, and return shape. This is thorough behavioral context.

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 informative but slightly longer than necessary. It is well-structured with a clear first sentence and subsequent details, but some redundancy (e.g., 'no payment, no arguments, works immediately' could be tightened). Still, every sentence 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 parameterless tool, the description covers everything an agent needs: purpose, usage, expiry, deletion, return shape, and unsupported operations. It even addresses edge cases like 'task won't fit in an hour'. Nothing 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 has zero parameters and the schema is empty. The description explicitly states 'no arguments', which adds clarity beyond the schema (which could be ambiguous if empty). No parameter explanations are needed, and the description handles it perfectly.

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

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

Description clearly states the action: 'Create a free trial workspace' and distinguishes it from the primary sibling (aanet_create_workspace) by explicitly comparing use cases. The verb, resource, and differentiator are all present.

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 states when to use this tool over the alternative: 'Use this instead of aanet_create_workspace when you want to exercise the API... before committing real money.' Also provides the exclusion: 'If your task won't fit in an hour, create a real workspace instead.'

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, and it does well: it warns that owner_key is generated once, never recoverable, and losing it means losing control; it also discloses that the workspace starts at 0 balance. However, the first sentence says 'with a prepaid USDC balance' while later stating the balance starts at 0, creating ambiguity about whether funds are already present.

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 dense but every sentence earns its place: purpose, sibling routing, return shape, critical key-loss warning, and funding prerequisite. It is front-loaded and well organized.

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?

Because there is no output schema, the description correctly includes the success return fields. It also covers the workspace's initial balance, the necessary deposit step, and the one-time owner_key handling. For a single-parameter creation tool, nothing essential 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 only parameter, label, is already fully documented in the schema as free text not required to be unique. The description adds no new parameter-specific meaning, so the high schema coverage baseline applies.

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

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

States a specific action: creating a real AANet workspace, and positions it as the entry point for an orchestrator starting a swarm task. It also distinguishes itself from aanet_create_trial_workspace, so an agent can immediately tell which tool is which.

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 names aanet_create_trial_workspace as the alternative for exploration before payment. It also gives operational guidance: fund the workspace with aanet_deposit before metered operations will succeed, making the prerequisite and sequence 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 provided, the description carries the full burden of behavioral disclosure. It does a good job: states it is irreversible, mentions the webhook event, details error codes (404, 409), and the return shape. However, it doesn't disclose prerequisites (e.g., need for a lock, permission requirements) or whether the operation is atomic or what happens on partial failure. For a destructive operation with zero annotation coverage, the description could go further, but it covers the most critical behavioral aspects.

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, with every sentence contributing meaning. It front-loads the core purpose and irreversibility, then adds webhook and error details, and finally the return value. No fluff or redundancy; it is well-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 the tool's complexity (4 params, no output schema, no annotations), the description is fairly complete. It covers the operation's effect, error scenarios, return shape, and even references related tools for parameter semantics. The missing piece is explicit prerequisites like acquiring a lock (since there is an aanet_acquire_lock sibling) and permission levels beyond what's in api_key descriptions. Still, it provides enough for an agent to use correctly in most 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 100%, meaning each parameter's description already provides detailed meaning (e.g., path, api_key, if_match, workspace_id). The tool description adds some nuance for if_match ('same conflict-detection purpose as on aanet_write_file') and references to other tools for api_key, but mostly the schema does the heavy lifting. Since the baseline is 3 due to high coverage, this score is appropriate; the description adds minimal extra value 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?

The description clearly states the tool's purpose: 'Permanently remove a file.' It also explicitly positions it within the file lifecycle alongside the sibling read/write/append tools, which helps distinguish it from other file operations. The verb 'remove' and resource 'file' are 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 mentions it is the 'missing piece of the file lifecycle' alongside specific siblings, implying when to use it (after read/write/append operations are complete). However, it does not explicitly state when NOT to use it, such as for directories (though it notes 409 for directories) or alternatives for recovery. It gives clear error contexts but no direct 'use this instead of X' 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, the description carries full burden. It discloses permanence, effect on active/auto-disabled webhooks, auth requirement (owner_key), and the new secret on re-registration. It lacks details on idempotency or error behavior, but is otherwise transparent about 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?

Two well-structured sentences: the first states the core purpose and effect, the second covers auth and the alternative path. Information is front-loaded and every sentence 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 deletion tool with no output schema, the description covers the essential context: what happens, auth constraints, and recovery via re-registration. It doesn't mention whether existing delivery logs are removed or what happens on failure, but these are minor gaps given the clear core behavior.

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 each parameter already has a detailed description, including the api_key distinction between owner and sub-key. The description adds only a reinforcement of the owner_key requirement, which is already present in the schema, so no significant extra value.

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

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

The description clearly states the action (permanently remove a registered webhook), the resource (webhook), and the outcome (no further events delivered). It distinguishes from siblings like aanet_register_webhook and aanet_list_webhooks by focusing on deletion.

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 explicitly provides when-to-use guidance: permanent removal with no pause option, and names the alternative (delete and re-register with aanet_register_webhook) for temporary needs. It also specifies the owner_key requirement, guiding correct invocation.

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 present, so the description carries the full burden. It fully discloses the irreversible, destructive nature ('no undo and no trash/recycle bin'), the authorization requirement (owner_key only; sub-key gets 403), and the consequence of deleting before refund ('once the workspace is gone, so is any way to claim what was left'). This is exemplary transparency for a destructive 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?

The description is dense but well-organized: it leads with the most critical fact (irreversibility), then the authorization requirement, then the refund ordering, and finally the usage context. Every sentence earns its place; there is no fluff. It is longer than typical but appropriately so given the destructive nature and the need to convey safety and sequencing.

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 destructive tool with no output schema and no annotations, the description covers all essential context: what is destroyed, who can call it, the prerequisite refund flow, and when to use it. An agent has enough information to decide whether and how to invoke it correctly. Nothing critical 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 input schema already provides complete descriptions for both api_key and workspace_id (100% coverage). The description does not add new parameter-level details beyond what the schema states; it focuses on usage and behavior. Since the schema fully documents the parameters, a baseline score of 3 is appropriate—the description adds no extra semantic value for 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 opens with a precise statement of the operation: 'Permanently and irreversibly delete a workspace' and enumerates exactly what is destroyed (sub-keys, files, activity log, webhooks). It clearly distinguishes this from sibling tools like aanet_delete_webhook and conveys the scope of destruction, making it unambiguous what this tool does and what it does not.

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 states when to use: 'Use this when a task is finished or permanently abandoned, not as a way to "reset" a workspace you plan to keep using.' It also provides a prerequisite sequence: call aanet_request_refund first if balance remains and wait for aanet_get_refund_status to show 'paid' before deleting. This is direct guidance with a clear exclusion, far above a baseline.

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 explicitly states that the first call does not charge anything, that the second call verifies and settles payment, and that a failed or already-used signature raises an error rather than silently no-op'ing. It also notes that the tool cannot sign for the user, which is critical behavioral context. This fully compensates for the lack of annotations.

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

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

The description is well-structured with clear step-by-step instructions separated by newlines. It front-loads the key information about the two-step nature and the constraint on trial workspaces. Every sentence adds value, covering prerequisites, the two steps, the return value, and error behavior. It is appropriately sized for the complexity without being verbose.

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 complexity (two-step x402 protocol), the description is complete. It covers the full flow, prerequisites (owner_key), error handling, and the return structure (workspace_id, deposited_units, tx_hash, network). There is no output schema, so describing the return format is essential and is provided. The description leaves no gaps that an agent needs to invoke the tool correctly.

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

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

The input schema has 100% coverage of all 4 parameters, each with detailed descriptions (e.g., api_key explains it can be owner_key or sub-key, amount_usd explains decimal string and minimum, payment_signature explains the two-step usage). Since the schema already provides comprehensive semantics, the description adds marginal value by reinforcing the two-step flow, but does not need to compensate for any gaps. Baseline 3 is appropriate as the schema does the heavy lifting.

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's purpose: to fund a real workspace via the x402 protocol. It specifies the action (fund), the resource (workspace), and the method (x402 protocol). It also distinguishes itself from the sibling aanet_create_workspace, noting that trial workspaces are not accepted, which helps differentiate it in the context of sibling tools like aanet_create_trial_workspace.

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

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

The description provides explicit when-to-use guidance: it tells the user to call the tool in two steps, explains the exact sequence (first call without payment_signature to get a challenge, then second call with the signed proof), and states that trial workspaces should not be used (use aanet_create_workspace instead). It also indicates that the tool requires the owner_key, and that the tool cannot sign the challenge itself, so sign with an external client. This is comprehensive and leaves no ambiguity about usage.

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 full behavioral burden and delivers: it discloses read-only semantics, owner-level authorization, the output field set including statuses, and the important trust property that the log cannot be faked or skipped. This goes well beyond the minimal 'get activity' phrasing.

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 paragraphs with no filler. The first sentence states purpose and trust value, the second paragraph covers output fields and recommended use cases, and every sentence 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 six parameters, no annotations, and an output schema present, the description supplies what an agent needs to select and invoke the tool correctly: purpose, authorization requirement, use cases, and output shape. The schema covers filtering parameters, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 even without extra parameter explanation. The description adds useful context about owner_key and the audit-log entry fields, but it does not elaborate on limit/since/operation/subkey_id beyond what the schema already documents.

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 ('Read') and resource ('server-side audit log of every attempt in this workspace'), making the tool's scope immediately clear. It also distinguishes itself as the authoritative source versus sub-agents' self-reports, which separates it from sibling data-read tools like aanet_get_messages.

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

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

Provides explicit use cases: reconstructing what happened after the fact and checking spend pattern before adjusting budget_cap via aanet_update_subkey. It also flags the owner_key requirement, though it does not explicitly name alternatives or exclusion conditions.

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 full burden. It discloses the lack of read/unread tracking server-side and instructs the agent to track its own last-seen timestamp, which is critical behavioral information. It also explains message visibility scoping (sub-key vs owner_key) and the pull-based nature. While it doesn't mention rate limits or explicit read-only status, the behavior is sufficiently covered for an agent to anticipate 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 information-dense but every sentence contributes meaning: the core function, the fallback context, visibility rules, and the tracking idiom. It is front-loaded with what the tool does, then adds necessary context. No filler or redundancy, and the structure flows logically from purpose to usage to caveats.

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 operational aspects: when to use, visibility semantics, and the lack of server-side state tracking. Since an output schema exists, the return format does not need to be explained in prose. For a message-fetching tool with visibility nuances, this description provides all the information an agent needs to call it correctly and interpret results.

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%, with detailed descriptions for each parameter. The description adds value by explaining the intended usage of `since` (track your own last-seen ts) and the auth model affecting what messages are returned, which goes beyond the schema text. It also references a sibling tool's pattern for consistency. This exceeds the baseline of 3 because it provides practical guidance not present in the schema.

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

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

The description clearly states the tool fetches messages sent via aanet_send_message, positioning it as a pull-based fallback to webhooks. It explicitly contrasts with webhook registration and names the specific verb 'fetch' with a concrete resource. This is distinct from sibling tools like aanet_get_activity, so an agent can immediately understand its unique role.

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 explicitly states the condition for use: 'when you haven't registered a webhook on the message event.' It also explains the alternative (webhook) and clarifies the visibility rules for sub-key vs owner_key, giving clear guidance on when to use it and what to expect. The mention of the 'same pattern as aanet_get_activity' for the `since` parameter provides cross-tool usage context.

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 full burden, and it delivers: it discloses the possible status values, the presence of tx_hash only once paid, the need to verify the transaction on-chain before treating a refund as confirmed or deleting the workspace, and the meaning of 'rejected' (amount credited back to the balance, not lost).

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 three sentences, front-loaded with the core action, and every sentence earns its place: one defines the purpose, one specifies required credentials and the verification caveat, and one clarifies the rejected-state semantics. No filler or repetition.

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 purpose, credential requirement, output semantics, and important post-verification behavior. Although an output schema exists, the description still explains the meaningful status values and the on-chain verification requirement, giving an agent everything needed to use the tool correctly in the refund workflow.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that the api_key must be the owner_key rather than a sub-key, which is a meaningful operational constraint not explicitly stated in the description field.

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 resource: 'Check the status of every refund request ever made for a workspace.' It also explicitly ties the tool to its counterpart, 'aanet_request_refund', making its purpose unmistakable and distinct from sibling getters like get_workspace or get_activity.

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: this is 'the way to find out whether an aanet_request_refund call actually got paid.' It also notes that Owner_key is required, which is an important precondition. It does not name alternatives to avoid or explicitly state when not to use it, but the use case is concrete 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?

No annotations are provided, so the description carries the burden. It discloses the output fields (event_type, status_code, success) and explains the special case where status_code is null (timeout/DNS failure). It also clarifies the api_key requirement (Owner_key). It does not explicitly state 'read-only' but 'inspect' implies it; this is adequate but could be more explicit.

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 primary purpose and use case. Every clause earns its place: the parenthetical about checking list_webhooks is essential routing guidance, and the output field breakdown is concise. No redundancy or fluff.

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

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

Given that the tool has an output schema, all parameters are fully described, and the description covers use cases, prerequisites, and output semantics, everything an agent needs to select and invoke the tool correctly is present. The tool is a simple read-style operation; no additional context is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by specifying that the api_key must be the Owner_key (not a sub-key), which is a meaningful clarification beyond the generic api_key parameter description. It also ties the output structure to the purpose but does not elaborate per-param usage beyond that.

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 ('Inspect one webhook's delivery history') and clarifies its purpose by contrasting with a sibling tool ('check aanet_list_webhooks first'). It also specifies the use case 'confirm an event actually fired', making the tool's scope 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?

Explicitly tells when to use it: to debug a quiet webhook or confirm an event fired, and even suggests a prerequisite step (checking aanet_list_webhooks for auto-disabled status). It also notes that Owner_key is required, which is a clear precondition.

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 full responsibility for behavioral transparency. It clearly marks the operation as read-only, explains the 402 use case, details the 'blocked' field's consequence (every metered call returns 403), and specifies raw integer units for deposit_balance and total_spent. This goes well beyond a generic 'gets workspace info' statement.

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 core purpose, then expands to return values and error behavior, and ends with a practical usage recommendation. Every sentence adds non-redundant information; 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?

Even without an output schema, the description fully explains returned fields (deposit_balance, total_spent, is_trial, blocked), unit semantics, and the 403/402 implications. It also clarifies key requirements and provides a concrete pre-flight use case, so an agent has everything needed to decide when and how to call it.

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 already fully documents both parameters (api_key and workspace_id) with detailed descriptions. The description adds some context by clarifying that api_key can be a sub-key, not necessarily the owner_key, and by tying usage to a 402 check. But most parameter meaning comes from the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource — 'Check a workspace's current balance and status' — and immediately distinguishes the tool as 'the read-only counterpart to every other workspace tool.' This makes the tool's role clear and separates it from sibling tools without needing to inspect their schemas.

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 concrete usage guidance: 'Call this before a batch of expensive operations to confirm you won't hit a 402 partway through.' It also explains the tool accepts owner_key or sub-key. It does not explicitly name a specific alternative tool, but the read-only-counterpart framing implies when this tool is appropriate versus other workspace operations.

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

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

With no annotations provided, the description carries the full burden. It discloses that revoked keys are included, that raw key values are never included (only shown once at creation), and that Owner_key is required. It doesn't mention pagination, ordering, or rate limits, but the key behavioral traits 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 with zero waste. The core scope is front-loaded, the complement relationship is stated, and the key behavioral caveat (raw keys never included) is included. Every sentence 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?

The description is complete for a list tool: it states scope, the complement relationship, the auth requirement, and the key exclusion behavior. With an output schema present, return values need not be explained. Minor gaps like pagination/ordering are not critical for a list tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds the Owner_key requirement context and clarifies the api_key's role, but doesn't add much beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a precise resource ('every sub-key ever issued under a workspace'), and explicitly includes revoked ones. It also names the sibling tool it complements (aanet_get_activity), distinguishing it from the per-event log. This is a clear, specific purpose statement.

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: it is the inventory view that complements aanet_get_activity's per-event log, and it notes the Owner_key requirement. It doesn't explicitly say when NOT to use it or name alternative tools for filtering, but the context is sufficient for an agent to select it appropriately.

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 present, so the description carries the behavioral burden. It adds meaningful disclosures: webhooks can be auto-disabled after repeated failures, secrets are never included and only shown once at registration, and the owner_key is required. It stops short of explicitly stating read-only safety or mentioning response pagination, but for a list operation this is strong transparency.

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 core action and return content are front-loaded, followed by critical caveats and an alternative-tool pointer. 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?

Given the tool's low parameter count, the rich input schema, and the presence of an output schema, the description covers everything an agent needs: purpose, key fields, owner_key requirement, secret-handling behavior, and a pointer to delivery history. No critical context is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents api_key and workspace_id. The description's 'Owner_key required' note reinforces the api_key schema but does not add new parameter-level meaning; workspace_id is already explained as sourced from workspace creation calls.

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 starts with a clear verb and resource: 'List webhooks registered on a workspace' and enumerates the returned fields (url, subscribed events, active/disabled status). It also implicitly distinguishes itself from webhook registration/deletion and explicitly points to a sibling for delivery history, so an agent can tell it apart without opening the schema.

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

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

It explicitly states when to use this tool and routes to an alternative: 'use aanet_get_webhook_deliveries for per-attempt delivery history on one of these.' It also conditions the call on requiring the owner_key, giving the agent a concrete prerequisite.

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 must carry behavioral disclosure, and it does: key is only displayed once, minting requires the owner key, and a sub-key cannot mint further sub-keys. It could also mention the full create-key lifecycle or rate limits, but the operational essentials are 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 definition is front-loaded with the single-sentence purpose, then adds constraints and usage best practices in a compact, readable sequence. Every sentence contributes meaning, and there is no redundant 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 five-parameter minting tool, the description covers input constraints, return behavior, security-relevant display limitation, and recommended usage pattern. It gives an agent enough context to invoke the tool correctly without ambiguous follow-ups.

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 already describes label, api_key, budget_cap, and path_scope in detail, so the description adds little per-parameter semantics beyond the owner_key restriction and return caveat. Baseline 3 is appropriate given the high schema coverage.

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 starts with a specific verb and resource: 'Issue a new scoped credential for one sub-agent' and positions it as 'the standard way to bring a sub-agent into a workspace.' This clearly differentiates it from workspace creation and sub-key revocation.

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 explicitly declares the prerequisite ('Requires the owner_key; a sub-key cannot mint another sub-key') and provides direct usage guidance: give each sub-agent its own sub-key rather than sharing one. It also names the sibling revoke tool (aanet_revoke_subkey) and explains why this pattern enables per-agent attribution and revocation.

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?

There are no annotations, so the description carries the full burden. It clearly explains metering, the exact return shape, and null-vs-list semantics for directories vs filescars, plus a concurrency tip about etag/if_match. It doesn't disclose failure modes like 403 or 404, but overall it gives substantial behavioral detail 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?

Everything is in 3 sentences, with return shape and branching behavior in a compact block. No fluff.

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

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

No output schema, but description explains return shape for both file/dir, and metering/usages. Auth semantics are in schema. Maybe missing explicit error behavior but not required for normal usage.

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%; the schema already documents api_key, workspace_idcher, and path. Description adds little to parameter semantics beyond mentioning the file-or-directory behavior of path, which is also partly in the description. Baseline 3 is appropriate.

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

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

The description names a precise operation (

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 is explicit about the branching behavior (file vs directory content), references aanet_write_file/aanet_append_file as the counterparts for writes, and tells the agent exactly when to save the returned etag for later use — clear practical selection criteria and workflow 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 full burden of behavioral disclosure. It comprehensively reveals: the secret is shown only once, the signature header format (X-AANet-Signature with HMAC-SHA256 keyed by that secret), billing per delivery attempt, auto-disable after 10 consecutive failures, and non-durability across service restarts. This goes far beyond what any annotation would typically cover, giving the agent a complete picture of the tool's side effects and failure modes.

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

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

The description is well-structured and front-loaded: it immediately states the purpose and the alternative, then provides critical warnings in a logical flow. It is dense but not verbose; every sentence adds value. The only minor issue is that it is longer than necessary for a simple registration tool, but given the safety-critical nature of webhook verification and billing, the length is justified. No filler or repetition exists.

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 complexity (webhook registration with signature, billing, failure modes, and durability concerns) and the lack of an output schema, the description is remarkably complete. It covers return values ({webhook_id, secret}), authentication requirements, event types, cost implications, and recovery behavior. The only minor gap is that it does not mention the exact HTTP status codes for success/failure, but that is not essential for an agent to call the tool correctly. The description equips the agent with everything needed to register a webhook and use it safely.

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

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

Schema description coverage is 100%, so the description's parameter-related info adds little beyond the schema. The schema already explains url validation, events allowed values, api_key types, and workspace_id sourcing. The description does not introduce new parameter semantics—instead, it mentions 'Owner_key required' which is already captured by the api_key description. Since the schema is fully self-documenting, the description does not need to add much, and the baseline of 3 is appropriate.

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

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

The description explicitly states the tool's purpose: 'Register a push endpoint' and clearly distinguishes it from polling alternatives. It names the specific sibling tools (aanet_get_activity, aanet_get_messages, aanet_acquire_lock) it replaces, making its role unambiguous. It also reveals the primary alternative (polling) and positions this as the push-based counterpart, which fully differentiates it from all siblings.

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 explicitly states when to use this tool: 'the main alternative to polling anywhere in this API,' and contrasts it with the GET tools. It also provides strong usage guidance by warning against using webhooks as the sole source of truth and recommending confirmation via GET tools for critical events. It even specifies the limiting condition (up to 5 active webhooks per workspace) and the required owner_key, giving clear prerequisites.

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 full disclosure burden. It reveals side effects (fires lock_available webhook), error conditions (404, 403), cost (free), and immediate nature of release. This covers key behavioral aspects an agent needs to know before calling.

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 sentences, each delivering distinct value: purpose, cost, errors, side effects. Front-loaded with the primary action and usage timing. No filler or redundancy; information-dense yet readable.

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?

Complete for a lock-release tool: covers when to use, error handling, side effects, and cost. References related tools (webhook registration, acquire lock) to guide integration. No missing operational details that would prevent 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 descriptions cover all three parameters thoroughly (api_key explains credential types and auth, workspace_id references creation tools, name specifies must-match condition). The description adds no extra parameter-specific meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Clearly states the action: voluntarily release a lock immediately, contrasted with waiting for lease expiry. Differentiates from sibling tools like acquire and renew by emphasizing immediacy and free cost. The verb 'release' plus resource 'lock' 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?

Explicitly instructs when to call ('as soon as you're done with the unit of work') and why (to avoid idle sub-agents). Contrasts with acquire/renew and mentions polling as an alternative to avoid, providing clear usage context. No ambiguity about the intended scenario.

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 failure modes (404, 403), the return value (lease_expires_at), and the core behavior (extending the lease). It does not mention side effects beyond lease extension, but that is the expected behavior and is clear.

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 well-structured: it states the purpose, tells when to use, gives failure conditions, and ends with the return value. Every sentence earns its place with no redundancy.

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 annotations and no output schema, the description covers the essential operational details: purpose, usage timing, failure modes, and return format. It is complete enough for an agent to call successfully, though it could mention idempotency or edge cases like invalid lease_seconds (though that is in 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 description coverage is 100%, so the baseline is 3. The tool description adds a small amount of context (e.g., 'you can't renew someone else's lease') that reinforces the api_key and name parameters, but it largely restates what the parameter descriptions already cover.

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 ('extend a lock'), the resource (a lock you currently hold), and explicitly distinguishes itself from the obvious sibling aanet_acquire_lock. This leaves no ambiguity about what the tool does and how it differs.

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 clearly tells when to use it ('before its lease runs out... while work is still in progress') and names the alternative (aanet_acquire_lock instead of calling it again). It also implies when not to use it via failure conditions (404 if nobody holds the lock, 403 for someone else's lease), but does not explicitly enumerate all scenarios.

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 exist, so the description carries the full burden, and it delivers: immediate balance zeroing, no double-payout because a second call fails, network fee deducted, failure when balance insufficient, and manual non-instant processing. These are exactly the behavioral surprises an agent must know before calling.

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?

Dense but every sentence earns its place: scope, preconditions, exclusion, immediate effects, fee model, and follow-up action. Nothing is wasted, and the key facts are front-loaded.

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 an irreversible-ish financial operation with no annotations and no output schema, the description covers prerequisites, exclusions, side effects, failure modes, and monitoring follow-up. An agent can invoke and observe this correctly without hidden surprises.

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

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

Schema description coverage is 100% and each parameter has a clear inline description span. The description adds contextual color about Owner_key and payout behavior, but does not need to repeat the parameters since the schema fully documents them. Baseline 3 is appropriate.

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

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

The description states a specific verb ('request refund'), a specific resource ('workspace's remaining balance'), and a clear scope (full balance back when task is done). It distinguishes this from nearby tools by naming the sequencing requirement before aanet_delete_workspace and the alternative polling tool aanet_get_refund_status.

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 tells the agent when to call it ('call this before aanet_delete_workspace, not after'), which credentials are required (owner_key, not sub-key), which calls reject it (trial workspaces), and what to do next (poll aanet_get_refund_status). This is clear decision 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses permanence, the immediate 401 effect on future calls, the release of any held lock (with an analogy to aanet_release_lock), and the scope (only the targeted sub-key). This is rich, non-obvious context that an agent needs to invoke safely and predictably.

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 focused paragraphs. The first sentence states the core purpose and effect, immediately followed by usage guidance and the owner_key prerequisite. The second paragraph adds the lock-release side effect, which is essential for understanding the tool's full impact. No word is wasted, and the most critical information is front-loaded.

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, the description covers the essential context: what it does, when to use it, side effects (lock release), and the authentication requirement. It does not describe the response format or error cases beyond the 401 for revoked keys, but for a destructive operation this is reasonably complete. An agent can invoke it correctly with the information provided.

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

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

Schema description coverage is 100%, so all three parameters (api_key, subkey_id, workspace_id) already have detailed explanations in the schema. The description adds little beyond what the schema provides; it mentions 'Owner_key required' but that is already implied by the schema's api_key description. Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description clearly identifies the verb ('Permanently revoke'), the resource ('one sub-agent's credentials'), and the precise effect ('every subsequent call with that key gets a 401'). It distinguishes itself from siblings like aanet_update_subkey (which likely modifies rather than revokes) and aanet_mint_subkey (which creates) by emphasizing permanence and scoping to a single sub-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?

The description explicitly states when to use the tool: 'when a sub-agent is compromised, misbehaving, or simply finished', and clarifies that it does not affect other sub-keys. It also notes the prerequisite 'Owner_key required'. It does not explicitly name alternative tools for temporary disablement, but the usage context is clear enough for an agent to decide.

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. It discloses one-shot semantics, webhook event on success, the return shape {message_id, ts}, and the non-durable/disposable nature of messages. It doesn't cover failure modes or delivery guarantees, but the core behavioral traits are clearly stated.

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 compact paragraphs with no filler. The primary action and recipient are front-loaded, and every sentence adds decision-relevant information about durability, webhooks, or return values.

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?

Despite having no output schema, the description states the return shape, explains the webhook integration path, clarifies recipient targeting, and gives usage examples. For a 5-parameter messaging tool with 100% schema coverage, this is complete enough for 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 description coverage is 100%, so the baseline is 3. The description adds useful context for the body (examples like 'chunk 3 done') and for to_subkey_id (broadcast behavior), but those meanings are also present in the schema. No additional parameter clarification is needed.

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

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

The description uses a specific verb and resource ('Send a one-shot signal directly to another sub-agent or to everyone'), gives concrete examples, and explicitly contrasts itself with aanet_write_file/aanet_append_file. An agent can immediately distinguish it from file-writing siblings.

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 explicitly tells when to use this tool vs alternatives: use write/append for durable state, pair with aanet_register_webhook instead of polling aanet_get_messages, and reserve messages for cheap disposable signals. The 'instead' language makes the routing decision explicit.

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

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

The description discloses the key behavioral trait that 'status' is always 'open' initially and there is no tool to check its status afterward - directly managing expectations about the asynchronous and fire-and-forget nature of the operation. It also states the return format ({feedback_id, status}) and what 'success' looks like versus failure. While the description doesn't mention rate limits or specific authorization details (owner vs sub-key permissions), the schema already covers which keys are valid. With no annotations provided, the description carries the behavioral burden well beyond what structured data offers.

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 about three sentences and packs in purpose, usage context, who can call, and a full behavioral explanation of the response and outcome. It front-loads the purpose and the non-support distinction, which is the most critical decision point for an agent. Every sentence adds meaningful information; there is no filler or redundancy.

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 the tool has 5 parameters all with good schema descriptions, no output schema, and no annotations, the description goes beyond covering the essentials. It explains the complete lifecycle: what happens upon submission (status always 'open'), that there is no polling tool, and what constitutes success. The addition about budget being the only prioritization signal and the honesty of '0' rounds out the contextual picture fully. There is nothing an agent needs to know to use this tool correctly that is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantics beyond the schema. Specifically, for 'pledged_budget_usd', it explains the declaration-only nature ('This is a declaration only — nothing is charged or reserved'), the prioritization relevance, and that '0' is a valid honest answer. The 'api_key' parameter gets context on what it is and how it's sent (Authorization header), which complements the schema's listing of allowed keys. The description also clarifies the output shape and the lack of a follow-up tool, enriching parameter 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 begins with 'Report a bug, request a feature, or flag that pricing feels wrong' - a specific list of actions on a specific feedback channel. It immediately distinguishes this from a support ticket, clarifying that this is a prioritization signal rather than a customer-service mechanism. The description clearly identifies the resource (feedback submission) and the scope (the only channel for this 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 description explicitly states when to use this tool ('this is the one feedback channel into how the operator prioritizes what to build next') and what it is not ('not a support ticket that gets a reply'). It also clarifies who can use it ('Any valid, unrevoked key can call this, owner or sub-key'), giving the agent clear context for invocation. It gives a clear schema of what happens after submission and that no follow-up tool exists, guiding expectations on usage.

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. It does disclose the critical partial-update semantics ('Fields left unset are unchanged, not cleared') and clarifies that it works 'live' without invalidating credentials. However, it omits details about the response format, error handling, or any side effects (e.g., whether changes are immediately reflected or atomic). While helpful, it does not fully cover the behavioral profile of a mutation 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?

Three sentences, each earning its place: the first defines purpose and the key alternative, the second gives concrete motivating examples, the third clarifies partial-update semantics. Critical info (purpose, alternative, partial behavior) is front-loaded, and there is no redundancy or fluff.

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

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

For a moderate-complexity mutation tool with no output schema and no annotations, the description covers purpose, usage, and parameter behavior well. However, it does not describe what the tool returns on success or failure, whether there are rate limits, or what happens if the subkey_id is invalid. Given the lack of an output schema, these omissions leave some gaps for an agent to safely invoke the tool.

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%, providing solid descriptions for all parameters. The description adds meaningful nuance: it clarifies that unset means 'unchanged' rather than 'cleared', and gives real-world examples for path_scope_prefix (widening file scope) and budget_cap (raising a cap it hit). This goes beyond the schema's generic 'Leave unset to keep the current value' by tying them to concrete use cases, so it compensates well despite the baseline.

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 ('Change') and resource ('live sub-key'), and explicitly distinguishes itself from the revoke-then-mint alternative, giving clear scope. It names exactly what it modifies (scope and/or budget cap) and what it avoids (revoking and reissuing), making it unmistakable even among 24 sibling tools.

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 explicitly says 'use this instead of aanet_revoke_subkey + aanet_mint_subkey' and gives concrete conditions (when credentials should keep working, e.g., widening scope mid-task or raising a budget cap). It also states the owner_key requirement, leaving no ambiguity about when to call this tool over others.

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 full behavioral burden, and it delivers: full overwrite semantics, create-if-missing behavior, webhook side effect, 409-on-conflict behavior, and the exact return shape. Nothing important is hidden.

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 tightly structured: core behavior first, alternative routing second, side effect third, and concurrency semantics last. Every sentence earns its place without redundancy.

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 and no annotations, the description is fully self-sufficient: it covers behavior, side effects, error handling, return shape, and the relevant sibling alternative. No essential calling information is missing.

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

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

Schema coverage is 100%, but the description adds meaningful behavioral context beyond the schema: it explains the compare-and-swap intent, the 409 consequence, and the 're-read, resolve, and retry' strategy for if_match. This goes beyond the basic etag description in the schema.

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

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

The description opens with a specific verb and resource: 'Overwrite a file's entire content, creating it if it doesn't exist.' It also distinguishes itself from the sibling aanet_append_file, making its purpose unmistakable.

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 explicitly states when to use an alternative ('use aanet_append_file instead if you want to add one entry without replacing what's there') and provides clear operational guidance for the compare-and-swap flow: pass if_match, handle 409 by re-reading, resolving, and retrying.

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