AANet

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

With no annotations provided, the description carries the full burden and does so: it discloses lease expiry semantics (lock becomes reclaimable after lease_seconds even mid-work), the 409 conflict response, the cost model for conflicts, the monotonic fence token, and the fence-passing contract with the write tools that enforces stale-writer protection. This is unusually rich 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?

Three tight paragraphs, front-loaded with the primary action and its timing rule, followed by lease lifecycle and then the fence/return contract. Dense with useful detail and little waste, though the fence paragraph could be marginally tightened.

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

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

Although there is no output schema, the description documents the success return shape ({lease_expires_at, fence}), the failure mode (409), and the cross-tool contract for using fence. Combined with 100% schema coverage, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by tying lease_seconds to the reclaim/renew/release lifecycle and by explaining fence (a return value the caller must thread into write calls). Name and api_key semantics are already fully covered by the schema.

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

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

States a specific verb and resource — 'claim exclusive ownership of a named unit of work' — and explicitly frames the intent ('so no other sub-agent starts the same thing'). It is clearly distinguishable from siblings like aanet_renew_lock, aanet_release_lock, and aanet_get_lock_status, which it names or implies by contrast.

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

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

Gives explicit timing guidance ('call this before starting work, not after') and routes the agent to the correct siblings for follow-up actions: aanet_renew_lock while still working, aanet_release_lock the moment work is done. It even clarifies that a lost race (409) is not charged, removing uncertainty about retrying.

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 delivers: it discloses the file_write webhook event, the 1 MiB cap checked before writing or charging, the fence guard shared with aanet_write_file, and the return shape {path, appended, etag}. That is exactly the behavioral context an agent needs for a mutating tool with zero annotation coverage.

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

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

Front-loaded with what the tool does and how it differs from the sibling, then layers in use case, side effects, limits, and return shape in compact order. Every sentence, including the error codes and return object, 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 9-parameter mutation tool with no annotations and no output schema, the description covers purpose, alternative, typical usage, side effects, failure modes, and the exact return object. Nothing material for a correct call 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 all nine parameters are already documented in structured data, establishing the baseline of 3. The description references the fence guard and stamp option only by pointing at aanet_write_file, adding cross-tool context but no new syntax or format detail beyond the schema.

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

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

States a specific verb (append) and resource (one entry to a file), plus the non-destructive semantics ('without touching what's already there'). It explicitly names the sibling it is not (aanet_write_file) and the condition that separates them, so an agent can route correctly without opening the 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?

Explicitly says when to use this tool instead of aanet_write_file, gives a concrete typical use case (shared log / running notes with multiple sub-agents), and describes rejection conditions (413 for >1 MiB) before side effects occur. Nothing about selection is left to inference.

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, and it does: exact pre-funded balance (1000 units), the 24-hour expiry independent of activity, permanent deletion of contents, rejection by aanet_deposit and aanet_request_refund, and even error behavior (413 on oversize writes). It also flags a known limitation rather than letting the agent infer a bug.

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

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

Front-loaded with purpose, key property, and the sibling routing in the first two sentences, then the operational details. It is denser and longer than most, and the nested parenthetical about the 1 MiB write cost is somewhat convoluted, but nearly every clause conveys actionable information.

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

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

No output schema exists, yet the description explains the return shape ('same shape as aanet_create_workspace plus trial_expires_at') and covers cost, lifetime, deletion semantics, and which sibling tools will reject the workspace. Nothing an agent needs to call this correctly is missing.

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

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

Zero parameters, so the baseline is 4. The description confirms 'no arguments', which matches the empty schema, but there is no additional parameter meaning to convey.

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

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

States a specific verb and resource (create a free trial workspace) and immediately distinguishes it from the sibling aanet_create_workspace, which is named explicitly. An agent can identify the tool's role without opening any schema.

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

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

Gives explicit routing: 'Use this instead of aanet_create_workspace when you want to exercise the API ... before committing real money', plus a clear when-not ('If your task won't fit in 24 hours, create a real workspace instead'). Both the selection condition and its boundary are stated.

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

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

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 behavioral burden and mostly delivers: irreversibility with no undo, a file_delete webhook side effect (cross-referenced to aanet_register_webhook), the 404 and 409 failure modes with their triggers, and the return shape {path, deleted}. The only omission is whether a sub-key is permitted or rejected with 403, but that is a minor gap against an otherwise unusually complete disclosure.

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

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

Three tight sentences: purpose first, then irreversibility and recovery caveat, then side effects, errors and return value. Nothing is redundant and no sentence is filler despite the density of information.

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

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

No output schema exists, so the description appropriately supplies the return value {path, deleted} along with error semantics and webhook side effects. For a six-parameter destructive tool with zero annotation coverage, everything an agent needs to call it correctly 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 description coverage is 100%, so the baseline is 3 and the schema already documents path, if_match, fence, fence_lock, api_key and workspace_id. The description still adds value by tying parameters to outcomes — path must be a file or yields 409, if_match mismatch yields 409 — which goes beyond the raw field docs.

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+resource ("Permanently remove a file") and immediately positions it against named siblings (aanet_read_file/aanet_write_file/aanet_append_file), so an agent can distinguish it from the other file operations without opening any schema. The destructive framing is unambiguous.

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

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

It establishes clear context — the deletion half of the file lifecycle — and warns that there is no undo and recovery requires an external backup, which is genuine when-to-use guidance. It does not, however, name an alternative path (e.g., a move/archive tool) or spell out a when-not-to-use condition beyond the implicit irreversibility, so it stops short of full routing guidance.

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

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

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?

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses that the first call charges nothing, the second call settles, the tool cannot sign challenges itself, failed or reused signatures error instead of no-op'ing, and success returns specific fields. This is exemplary transparency for a mutation-like 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?

The description is longer than average but every sentence earns its place, given the two-step protocol. It front-loads the core purpose and key restrictions, then uses numbered steps with clear conditions imparted in sequence. No filler or redundant restatement of the tool name appears.

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?

This tool has no output schemacarska and moderate complexity, but the description fully compensates by enumerating the success return fields, the networks offered, the minimum amount, error behavior, and step-specific parameter usage. An agent has all the information needed to correctly execute both calls.

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?

Although schema coverage is 100%, the description adds substantial meaning beyond parameter names and types: it ties amount_usd to an identical-value requirement across both calls, explains payment_signature as the signed proof and when to leave it unset, and clarifies the api_key must be the owner_key. This goes well beyond the schema's field descriptions.

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

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

The description clearly states the tool's purpose: funding a real workspace via the x402 protocol in two steps. It distinguishes itself from trial workspace creation and names the sibling tool for creating a fundable workspace, leaving no ambiguity about its scope.

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 says when to use this tool versus alternatives, noting that trial workspaces are not accepted and pointing to aanet_create_workspace for a fundable one. It also provides structured step-by-step usage instructions, including when to omit payment_signature and when to provide it, and highlights the owner_key requirement.

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 does so well: it discloses the exact cost model (~16 units/round at $0.00001/unit vs ~9,600 tokens/round at $2-$10/M), states it has no side effects or spend, and flags that the result is a rough estimate, not a quote.

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

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

Front-loaded purpose followed by the assumptions and the caveat, all earning their place. The numeric assumption sentences are dense but necessary for interpreting the estimate; only slight verbosity.

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 pure computation tool with no output schema: the agent knows what inputs mean, what the calculation assumes, and that the result is approximate. Nothing critical is missing, though the response shape itself is left unspecified.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description explains the model that consumes them but adds no per-parameter semantics beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource — 'estimate the cost of coordinating a swarm on AANet versus relaying... through your orchestrator's LLM context' — and the comparison is unique among siblings, none of which estimate cost. An agent can distinguish this from the create/spend tools immediately.

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

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

Gives clear timing ('before you create a workspace or spend anything') and routes the agent to aanet_get_activity for actual measured cost once running. No explicit when-not-to-use case, but the pre-decision context is unambiguous.

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 does reasonably well: it discloses ordering (ascending), the returned cryptographic fields, that the signed head is included, the pagination mechanism, and the credential requirement plus that the call is free. It stops short of stating rate limits or what happens on a tampered chain, but the behavioral picture is largely complete.

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, front-loaded with what is exported, then paging, then verification and auth/cost. Every clause carries distinct information and nothing is repeated.

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

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

There is no output schema and no annotations, so the description must cover returns and behavior; it describes the row shape and the included signed head, plus paging, verification, and credential requirements. Only minor gaps remain (rate limits, error behavior on chain mismatch, how the head is consumed).

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 limit, api_key, since_seq, and workspace_id, and the baseline is 3. The description only restates since_seq's paging role in prose ("the last chain_seq you got") without adding format or constraint detail beyond the schema's "chain_seq greater than this".

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 ("Export the hash-chained (OK) audit rows") and enumerates the payload (prev_hash/entry_hash plus the signed head), which separates it from plain activity readers. It never names the adjacent siblings (aanet_get_activity, aanet_get_activity_head, aanet_get_activity_summary) that an agent must choose between, so differentiation is implied rather than explicit.

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

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

It gives concrete operational guidance: page forward using since_seq = the last chain_seq received, verify with the verify_chain function in AGENTS.md, and notes the auth/cost profile ("Owner_key required; free"). What's missing is an explicit when-not or a pointer to the lighter activity tools for non-verification reads.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the audit log includes both successful and rejected attempts, that the record is server-side and tamper-resistant ('sub-agents can't fake or skip this'), the owner_key requirement, and the status vocabulary (OK, INSUFFICIENT_BALANCE, SCOPE_DENIED, CONFLICT). It does not discuss volume, rate limits, or retention, which keeps it short of a 5 for a read tool with zero annotation coverage.

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?

Purpose is front-loaded in the first clause, followed by entry contents and then usage. Three sentences are tight and each carries information, though the aside about sub-agents misreporting their own actions is more rhetorical than operative.

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?

An output schema exists so return values need not be explained, and the schema fully documents all 7 parameters. The description covers purpose, auth prerequisite, and workflow context, leaving only pagination and result-volume expectations unaddressed — a minor gap for a straightforward read 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 every parameter including limit, since, since_id, operation and subkey_id is already documented in the schema, setting the baseline at 3. The description confirms the shape of returned entries but adds no filter syntax, cursor mechanics, or defaults beyond what the schema states.

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

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

States a specific verb and resource: 'Read the server-side audit log of every attempt in this workspace, successful or rejected.' The 'every attempt, including rejected ones' framing plus the enumeration of raw entry fields (subkey_id, operation, status) effectively separates it from the summary-style sibling without the agent needing to open either schema.

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

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

Gives two concrete use cases ('reconstruct what happened after the fact', 'check a sub-agent's spend pattern before adjusting its budget_cap via aanet_update_subkey') and states the owner_key prerequisite. It stops short of naming the competing alternative (aanet_get_activity_summary) or saying when NOT to use this tool, so it is clear context without explicit 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, the description carries the burden well: it discloses that any key may read it, that it reveals no activity, that the signature is Ed25519 by the service, and that the call is free. It omits rate limits and error/edge behavior, but adds substantial behavioral context 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?

Front-loads the core purpose and the returned fields, then appends the verification rationale and public-key URL. Dense but every sentence carries information; the parenthetical asides are slightly heavy but not wasteful.

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 no output schema and no annotations, the description covers the return fields, access model, cost, cryptographic algorithm, the public-key retrieval URL, and the intended verification procedure. An agent has everything needed to call and use it correctly.

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

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

Schema description coverage is 100%, so api_key and workspace_id are already fully documented in the schema. The description adds no additional parameter meaning, so 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?

States a specific verb+resource ('Signed tip of the workspace's tamper-evident activity chain') and immediately enumerates the exact return shape {seq, entry_hash, signed_at, key_id, algorithm, signature}. It is clearly distinguishable from siblings like aanet_get_activity, aanet_get_activity_summary, and aanet_export_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?

Gives a concrete when-to-use scenario ('Save it OUTSIDE AANet... if the operator later rewrote or deleted earlier rows, a fresh export no longer contains your saved entry_hash at that seq'), which frames the verification workflow. It does not explicitly contrast with or exclude the sibling activity/export tools, so it stops short of naming 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?

No annotations are provided, so the description carries the burden. It discloses two real behavioral facts beyond the schema: 'Owner_key required' (a permission/credential constraint) and 'An unknown group_by is an error' (failure mode). It does not state what the totals are scoped to by default beyond the schema default, but for a read-only aggregation tool this is solid disclosure.

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: output shape first, then the use case plus follow-on tool, then the two constraints. Front-loaded with the value proposition and free of 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?

An output schema exists, so return values need not be detailed, yet the description still names the key fields. Combined with 100% schema coverage and the explicit credential/error notes, an agent has everything needed to call this correctly relative to its sibling tools.

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. The description adds meaning on top: it emphasizes that an owner key is required for api_key, and that an unrecognized group_by value errors rather than falling back to a default — both facts the schema does not state explicitly.

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+resource+output shape: it aggregates spend totals from the audit log, returning per-group total_cost (units) and calls. It also distinguishes itself from the raw-log sibling by saying it works 'instead of reading every entry', so an agent can route between this and aanet_get_activity without opening either schema.

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

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

Gives explicit context and the follow-on action: 'Use it to see which sub-agent is burning budget before adjusting a budget_cap via aanet_update_subkey.' It also states the when-not condition (don't read every entry) and the alternative tool by name.

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 does well: it discloses the owner_key auth requirement, that the call is free, that the figure is an audit-log estimate rather than a guarantee, and that young workspaces skew the hourly rate. It doesn't restate the read-only nature of the call or mention rate limits.

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

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

Front-loads the deliverable and is dense with useful detail, including the output field names (measured_since, covered_seconds, shortened) that no output schema provides. The young-workspace caveat is stated twice in slightly different words, which is the one element that doesn't fully earn 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?

There is no output schema, so the description must describe return values — and it does, enumerating the windows, the runway figures, the top spending sub-keys, and the per-window measurement metadata. Nothing an agent needs to interpret the response 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% — both api_key (including the sub-key 403 behavior) and workspace_id are fully documented in the schema. The description's 'Owner_key required' reinforces the auth rule but adds no syntax or format detail beyond it, so the baseline 3 applies.

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

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

Names a specific resource and deliverable — burn rate and runway, spend per hour over 1h/24h/7d windows, top spending sub-keys — so an agent knows exactly what it computes. It never explicitly contrasts itself with the adjacent sibling aanet_get_remaining_balance, so the boundary between 'balance' and 'forecast' is left to inference.

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

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

Gives clear operational context: 'Owner_key required; free' and a concrete use case — pair with a balance_low webhook to be warned before a 402. It stops short of naming an alternative tool to use instead when only a raw balance is wanted, and states no 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, the description carries the full burden and does: it discloses that this is a non-acquiring read, enumerates the four possible statuses with their meanings, lists the fields returned in each state, warns that release is not proof of success, and states the cost model (1 unit; unknown name = free miss).

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

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

The key distinction is front-loaded and every clause carries information (statuses, fields, semantics, cost). It is dense and slightly awkward with the nested quoted phrases, but there is no filler sentence.

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

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

With no output schema and no annotations, the description fully compensates by specifying the return shape (status enum plus per-state fields), the semantic interpretation of each value, and the cost of a miss. An agent can call and interpret the result without any other source.

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 api_key, workspace_id, and name are already fully documented in the schema; the description adds only the edge-case semantics of a never-acquired name, not parameter syntax or format. 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?

States a precise verb and resource (check a lock) and immediately scopes it against the sibling: it does NOT take the lock, unlike aanet_acquire_lock. It further clarifies the exact ambiguity it resolves (free vs. released), which no sibling does.

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

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

The description makes the selection condition clear: use this instead of aanet_acquire_lock when you need to distinguish a free lock from a released one. It also gives the follow-up rule to confirm work success via the result file, but it does not explicitly state when not to use it (e.g., when you intend to acquire).

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 behavioral burden and does so richly: billing semantics (waiting free, only a returning call costs 1 unit, timeout is free), rate limits (3 waiting calls per key, 16 service-wide, else 429), visibility rules (sub-key sees addressed messages plus broadcasts; owner sees everything), and the absence of server-side read/unread tracking. This is exactly the operational context an agent needs.

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

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

Front-loaded with the purpose and the webhook-fallback framing before diving into wait/listen behavior, billing and limits. It is dense and multi-topic for a short description, but nearly every sentence carries operative information (timeout cost, 429 thresholds, owner-vs-sub-key scope) rather than 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?

An output schema exists so return values needn't be explained, and the description covers the remaining gaps: billing, concurrency limits, visibility scope and cursor strategy. Nothing an agent needs to invoke this correctly (long-poll usage, cost, throttling, cursor) 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 documents wait, limit, since, since_id and topic in detail; the description largely echoes that (e.g., dedupe by id, since_id as recommended cursor). It adds the cross-tool framing for the cursor but no new syntax or constraints beyond 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?

States a specific verb and resource ('Fetch messages sent via aanet_send_message') and immediately frames it as the pull-based fallback to webhooks, which cleanly distinguishes it from aanet_send_message, aanet_get_webhook_deliveries and aanet_register_webhook. An agent can identify the tool 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?

Explicitly names when to use it (no webhook registered on the message event; agents that cannot receive webhooks) and the alternative pattern (wait>0 long-poll instead of tight polling, pass since_id=<last id>). It also cross-references aanet_get_activity for the same last-seen cursor pattern, giving the agent a routing decision, not just a description.

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 does add real context: 'Free, no key needed' discloses the auth/access profile, 'Same document as GET /pricing' identifies the underlying endpoint, and 'the prices are exactly what is charged' pre-empts questions about staleness or approximation. It does not state the response structure beyond a content inventory, which keeps it off a 5.

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

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

Front-loaded with the most decision-relevant facts (free, no key) and the content inventory, then the usage pointer. It is a single dense sentence plus two short clauses, with a little redundancy between 'Free, no key needed' and 'Same document as GET /pricing', but nothing that should be cut wholesale.

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-param read-only tool with no output schema and no annotations, the description covers what an agent needs: access requirements, what the returned document contains, the unit of pricing, and when to call it. The only gap is the concrete response shape (key names), which is minor given the enumerated contents.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly adds no parameter guidance.

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+resource ('the machine-readable price list') and enumerates exactly what it contains: per-operation cost in units, base + per-KB pricing, minimum deposit, file-size and webhook limits, trial terms, and the idle-storage fee. It is clearly distinguishable from siblings such as aanet_estimate_savings, which it explicitly cross-references.

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

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

'Use it to budget a swarm before creating a workspace (see also aanet_estimate_savings)' gives a concrete use context and names the nearest alternative. It stops short of an explicit when-not or a routing rule ('use X instead when Y'), so it is clear but not fully prescriptive.

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?

With no annotations, the description carries the full behavioral burden and does so well: it declares the tool is free/never charged, that it takes only the key, that it works for owner_key or any sub-key 'against itself', and it explains each returned field including null conditions and the fact that `remaining` is the minimum of the others. This is far beyond what structured fields provide.

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

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

Front-loads the purpose and the free/no-charge fact, then details the return fields. Two dense paragraphs with little waste, though the field-by-field enumeration and the parenthetical unit note are slightly 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?

No output schema or annotations exist, so the description must explain return values, and it fully documents all four fields, their units, and their null semantics. Nothing needed to call or interpret this tool 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% and the api_key field already documents owner_key vs sub-key and the 403 behavior. The description mostly restates this ('works for the owner_key or any sub-key'); only 'against itself' adds marginal new meaning, 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?

States a specific verb and resource ('how much this key can still spend') and frames the scope precisely as the balance for the calling key. An agent can immediately distinguish this from siblings like aanet_get_workspace or aanet_get_forecast, which cover workspace-level and predictive data rather than per-key spendable balance.

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

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

Gives a clear motivating context ('stop before a 402 instead of discovering it mid-sequence'), which tells the agent when to call it. It does not name explicit alternatives (e.g. aanet_get_forecast) or state when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it states Owner_key is required, explains status_code=null (timeout or DNS failure) and skipped=true (workspace could not afford delivery, not billed, not an endpoint failure). It does not explicitly state that the tool is read-only or describe retention limits, so it falls short of exhaustive disclosure.

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 purpose and usage, then explains the delivery-record fields without wasted words. Every sentence adds actionable information.

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

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

Given a complete schema and an output schema, the description fills the remaining gaps: auth requirement, usage context, and interpretation of key return fields. Nothing an agent needs to select or invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented. The description adds only 'Owner_key required,' which overlaps with the schema's detailed api_key description and adds no new syntax or format details.

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: inspecting one webhook's delivery history. It clearly distinguishes this from sibling tools like aanet_list_webhooks, which is named as a prerequisite rather than 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?

It gives explicit when-to-use guidance: debug a webhook that has gone quiet, check aanet_list_webhooks first for auto-disablement, and confirm an event fired. The condition selecting this tool is unambiguous.

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, the description carries the full burden and does well: it discloses that revoked keys are included, that raw key values are never returned (and why — shown once at creation), and that an owner key is required. It does not mention pagination or result-size behavior, which is the remaining gap.

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

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

Two compact sentences that front-load the inventory scope and field list, then add the owner-key and raw-value caveats. Every clause conveys information that changes how an agent calls or interprets the tool.

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

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

An output schema exists, so return-value documentation is not needed. Given that, the description covers scope (all keys, including revoked), field contents, auth requirement, and the security caveat about raw values — everything an agent needs to invoke and interpret this correctly.

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

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

Schema description coverage is 100% and both parameters are fully documented there (including the 403-on-subkey rule). The description only restates 'Owner_key required', adding no format or syntax detail beyond the schema. Baseline 3 for high coverage 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?

States a specific verb and resource ('List every sub-key ever issued under a workspace') and enumerates the returned fields (scope, budget_cap, window/rate limits, spent_so_far). It explicitly positions itself against the sibling 'aanet_get_activity's per-event log', so an agent can distinguish the two without opening a 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 phrase 'the inventory view that complements aanet_get_activity's per-event log' names the alternative and the axis on which to choose between them (inventory vs. event log). It also flags the 'Owner_key required' precondition. There is no explicit when-not-to-use statement, but the routing context is 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?

No annotations, yet the description discloses everything material: secrets are never included, disabled reason follows 10 consecutive failures, skipped deliveries for empty balance don't count, and an aanet.system message is emitted on auto-disable. That is rich behavioral context that annotations would normally carry.

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

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

Front-loads the action and the returned fields, then follows with the failure/disable semantics and the sibling routing. It is dense but every clause earns its place; only the parenthetical about empty-balance deliveries is slightly buried.

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

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

With an output schema present, the description needn't describe return shape, and it still explains field meaning (consecutive_failures, disabled_reason trigger). Auth requirement, secret exclusion, and sibling routing are all covered for a read-only 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 baseline is 3. The description adds 'Owner_key required', which tells the agent that a sub-key will be rejected even though the schema allows either key type — a real semantic addition beyond the schema.

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

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

States a specific verb (list) and resource (webhooks on a workspace), and enumerates the fields returned: url, subscribed events, consecutive_failures, disabled_at/reason. It is clearly distinct from aanet_get_webhook_deliveries and aanet_register_webhook, which it names.

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?

Says 'use aanet_get_webhook_deliveries for per-attempt delivery history on one of these', which is a clear routing hint. It doesn't spell out when not to use this (e.g., no-all-workspaces case), but the context is clear enough for an agent.

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 does well: it discloses the owner-only auth requirement, the one-time reveal of the secret key, and the safety semantics of each limit. It does not cover failure modes for the mint call itself (e.g. invalid owner_key, duplicate label), leaving a small gap for 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 short paragraphs, front-loaded with purpose, then return/auth caveats, then limit rationale. Every sentence adds something, though the swarm/revocation sentence is slightly expansive for a tool definition.

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

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

Despite having no output schema, the description documents the return shape ({subkey_id, key}) and the crucial one-time-reveal property, plus the auth constraint and limit semantics. An agent has everything needed to call it correctly and reason about the result.

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

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

Schema coverage is already 100%, so baseline is 3. The description adds genuine rationale beyond the schema by explaining why budget_cap and the per-window limits exist ('contain a sub-agent stuck in a loop long before it spends its whole budget_cap'), which helps an agent choose sensible values rather than merely understand the fields.

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

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

States a specific verb and resource ('Issue a new scoped credential for one sub-agent') and immediately frames it as the standard onboarding path. It distinguishes itself from siblings by naming aanet_revoke_subkey and aanet_get_activity as the tools whose behavior this key structure enables.

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 says when to use it (bringing a sub-agent into an existing workspace), states a hard precondition (requires the owner_key; a sub-key cannot mint another sub-key), and gives a directive on the correct pattern (one key per sub-agent rather than sharing). The alternative pattern is also explained via the attribution/revocation rationale.

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 does so well: it discloses cost accounting ('1 unit per hit'), that a missing path returns 404 and is free, the exact response shape, and the concurrency/etag protocol for avoiding clobbered writes. These are behavioral traits an agent could not infer from the schema.

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

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

The core behavior and the sibling relationship are front-loaded, and every sentence carries information (cost, return shape, etag protocol). It is dense but slightly over-packed, with the directory/file return-shape explanation taking two passes to parse.

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

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

No output schema exists, but the description compensates by specifying the return object keys and how content/entries invert between file and directory cases. Combined with cost and etag guidance, an agent has everything needed to call this correctly and chain it into a write.

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, but the description adds real semantic value: 'path' may resolve to a file or a directory and the tool branches its behavior accordingly, and 'etag' is surfaced as a cross-tool parameter for writes. It does not elaborate on api_key/workspace_id beyond the schema, which is fine.

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+resource ('Read a file's content') and extends it to the directory-listing case, explicitly positioning itself as 'the read counterpart to aanet_write_file/aanet_append_file'. An agent can distinguish it from every sibling without opening a 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?

Explicitly frames when to use it relative to write/append siblings and gives the concrete follow-up flow (save the etag, pass it as if_match on aanet_write_file). It does not state when NOT to use it (e.g. versus aanet_get_workspace for metadata), so it stops short of full alternative coverage.

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 does so exhaustively: one-time secret return, HMAC-SHA256 signature verification with the header name, 2-unit billing per attempted delivery, skipped-when-unaffordable semantics, 15-minute retry for 24 hours, auto-disable after 10 consecutive failures, at-least-once durable outbox with backoff and a dedupe header. This is far beyond what any structured field conveys.

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

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

Front-loaded with purpose and the polling alternative, then layered with the operational details that matter most. It is dense and on the long side, and a phrase like 'the main alternative to polling anywhere in this API' partially repeats the opening clause, but nearly every sentence carries distinct, decision-relevant information given the absence of annotations and output schema.

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

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

With no annotations and no output schema, the description still covers the return shape ({webhook_id, secret}), the full delivery/billing/failure lifecycle, and the sibling tools for monitoring (aanet_list_webhooks, aanet_get_webhook_deliveries, aanet_get_activity). Nothing an agent needs to invoke or correctly reason about the tool 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 meaning the schema does not: it flags the owner_key requirement for api_key and the 5-webhook-per-workspace cap on url registrations. It does not add format detail for events or balance_thresholds, which the schema already handles well.

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

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

States a specific verb and resource ('Register a push endpoint') and immediately frames the scope by contrasting it with the polling loop tools it replaces (aanet_get_activity/aanet_get_messages/aanet_acquire_lock). An agent can distinguish this from every polling sibling without opening a 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?

Explicitly states when to use it (in place of polling) and names the alternative tools being replaced. It also adds the key precondition ('Owner_key required') and a hard limit ('up to 5 active webhooks per workspace'), plus a when-not-to-rely-on-it caveat directing the agent to confirm with the matching GET tool.

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

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

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 behavioral burden and does well: it discloses 404 and 403 failure cases, describes the return payload, and notes that fence is unchanged by a renew. It does not mention idempotency or auth behavior, though those are covered in the schema.

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

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

The description is compact and front-loaded: the primary action and the acquire-lock alternative come first, followed by failure modes and return semantics. Every sentence adds useful information.

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

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

For a lease-renewal tool with no output schema, the description explains the action, the key failure modes, and the return fields, including fence stability. Combined with the 100%-covered input schema, an agent has enough information to call it correctly.

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

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

Schema description coverage is 100%, so parameter meaning is already documented in the input schema. The description reinforces the lease-renewal context but does not add parameter-level detail 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 states a specific verb and resource: "Extend a lock you currently hold." It also distinguishes this from the sibling acquire tool by explicitly saying to call this instead of aanet_acquire_lock again while work is still in progress.

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 usage guidance: renew before the lease runs out, and use this rather than re-acquiring while work is in progress. It also names the conditions under which the call fails, which helps an agent understand when this tool is appropriate.

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 does so richly: it discloses that the balance is reserved/zeroed immediately, that a second call fails rather than double-paying, that the network fee is deducted (net_payout_usd = gross - fee), that insufficient balance relative to the fee causes failure before reserving, and that payout is manual rather than instant.

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

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

Front-loads the purpose and the ordering constraint, then layers in behavioral details. The prose is dense but every sentence contributes a distinct behavioral fact; it is slightly long but not padded.

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 annotations and no output schema, the description covers preconditions, side effects, failure modes, fee handling, one response field, and the polling follow-up. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, establishing the baseline of 3. The description only restates the owner_key requirement, adding little beyond what the schema's api_key description already says.

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

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

States a specific verb and resource ('Ask for a workspace's entire remaining balance back') with clear scope ('entire remaining balance'). It explicitly positions itself relative to sibling aanet_delete_workspace ('call this before ... not after'), so an agent can distinguish it without opening any schema.

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

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

Gives explicit preconditions (task done, money left over), ordering relative to a named sibling, and exclusions (trial workspaces reject this outright, owner_key required). It also names the follow-up tool, aanet_get_refund_status, for the outcome.

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 burden. It discloses that messages are cheap/disposable, not durable, fires a webhook event on success, and returns {message_id, ts}. It does not cover auth/permission behavior or delivery guarantees, but the core 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?

Well-structured with the purpose first, then alternatives, then cost/webhook/return. Slightly verbose with the multi-line examples and parenthetical webhook reference, but every sentence carries information.

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

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

Complete enough for a fire-and-forget messaging tool with full schema coverage: purpose, alternatives, cost, webhook coupling, and return shape are all present. Missing only error/auth edge cases, which are less critical given the schema.

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

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

Schema coverage is 100% and every parameter already has a description, so the schema does the heavy lifting. The description adds the broadcast-vs-targeted semantics ('or to everyone') but nothing on idempotency or topic 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?

States a specific verb+resource (send a one-shot signal to another sub-agent or everyone) and explicitly contrasts with aanet_write_file / aanet_append_file. An agent can tell exactly what this does versus the file-write 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?

Gives concrete when-to-use examples ('chunk 3 done', 'aborting, don't wait on me') and names the alternative tool for persistence, plus the webhook pairing instead of polling aanet_get_messages. Explicit routing guidance.

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

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

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 present, so the description carries the full burden, and it does most of it: it discloses the mutation semantics ('Fields left unset are unchanged, not cleared'), the exception carve-out for the three limit fields, and the auth requirement ('Owner_key required'). It stops short of stating failure modes (revoked/nonexistent sub-key, sub-key caller 403) or whether changes take effect immediately for a running sub-agent.

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 dense sentences, front-loaded with the purpose and the routing rule before the field semantics. Slightly packed — the unset/cleared parenthetical could be tighter — but every clause carries actionable information and nothing is padding.

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 8-param mutation tool with no annotations and no output schema, the description covers what the tool changes, why to prefer it, and the subtle PATCH-style null semantics. Missing only error/failure conditions and confirmation of what a successful call returns or how it appears to a live sub-agent.

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

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

Schema coverage is 100% and the field descriptions already carry the per-field unset/zero semantics, so the description's note about unset-vs-clear largely restates structured data. It adds modest cohesion by grouping the three limit fields as a single behavior, but no new syntax or format detail.

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

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

States a specific verb and resource ('Change a live sub-key's scope and/or budget cap') plus a defining constraint ('without revoking and reissuing it'). An agent can distinguish this from aanet_revoke_subkey and aanet_mint_subkey on the description alone.

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

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

Explicitly routes: 'use this instead of aanet_revoke_subkey + aanet_mint_subkey when the sub-agent's credentials themselves should keep working', with two concrete trigger scenarios (widening scope mid-task, raising a hit budget cap). Names the alternatives and the condition that selects this tool over them.

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

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

With no annotations provided, the description carries the full burden and succeeds: it discloses the webhook side effect, CAS conflict behavior, stale-fence rejection, size-limit rejection before writing or charging, and the return shape. These are exactly the behavioral traits an agent needs before invoking a mutating 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 front-loaded with the primary action and the most important alternative (`aanet_append_file`), then layers conflict, size, and lock details. Every sentence adds operational value with 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?

For a mutating tool with no annotations and no output schema, the description is complete enough to call correctly: it explains side effects, error conditions, recovery behavior, and the return fields. Nothing essential is left for the agent to infer.

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 meaningful semantics beyond the schema for `if_match`, `fence`, and the content size limit. It does not elaborate on every parameter such as `stamp` or `fence_lock`, but the schema already covers those adequately.

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

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

The description gives a specific verb and resource: overwrite a file's entire content and create it if absent. It also explicitly distinguishes this from the sibling `aanet_append_file`, so an agent can route between them without comparing 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 states exactly when to use this tool versus `aanet_append_file`, and explains when to use `if_match` for compare-and-swap and `fence` for lock-guarded writes. It also tells the agent how to recover from a 409 rather than blindly retrying.

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