THE RETREAT

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

Annotations only cover the safety profile (destructive=false, openWorld=false) and carry no behavioral content. The description goes further: it discloses the rule-based nature ('predefined risk patterns'), the return shape (matched findings plus proceed/revise/stop), the scope limitation ('does not understand or verify your plan'), and a cost cue pointing at list_treatments. It does not discuss the credit-charging/idempotency mechanics beyond that pointer, keeping it short of 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?

Purpose is front-loaded in the first sentence, followed by the mechanism, the return value, the crucial disclaimer, and the pricing pointer. No filler sentences, though the scope disclaimer and pricing note could be trimmed slightly into one sentence each.

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

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

With no output schema the description correctly supplies the return semantics (findings plus proceed/revise/stop) and is honest about the non-verifying nature, which is the most important thing to know. But for a 9-parameter tool with 44% schema coverage it leaves several inputs (kind, stakes, reversible, meta) unexplained, so it is adequate rather than complete.

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

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

Schema coverage is only 44% across 9 parameters. The description explains none of the high-value inputs — kind, stakes, reversible, context, or the public-label meta fields — and only obliquely touches pricing ('see list_treatments'). That is insufficient compensation for the coverage gap.

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

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

States a concrete action on a concrete input: 'Checks text for predefined risk patterns: destructive verbs, missing rollback cues, absolute claims, assumptions and missing evidence.' The metaphorical name cold_plunge is fully disambiguated, and it is clearly not one of the other retreat-style siblings (meditate, sauna, garden_exchange).

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

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

Usage is implied by 'A checklist for risky actions and unsupported claims' and the caveat that it is not a verification step, so an agent can infer it is a pre-action review. However, there is no explicit when-to-use/when-not, no mention of when to prefer it over running the task directly, and no named alternative.

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

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

Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description goes beyond them by disclosing that output categories are provisional and that 'Known' reflects the claim's wording rather than the system's verification — genuinely useful interpretation context. It omits auth requirements (api_key) and any note about the cost actually being charged per run.

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 and the sentences are short with no filler. The telegraphic style ('Known means...', 'Treat all categories as provisional') is efficient, though a few clauses read as notes rather than structured guidance.

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 6-parameter tool with a nested meta object and no output schema, the description covers output interpretation and cost sourcing reasonably well. Its main gap is failing to explain the relationship between 'text' and 'statements' or how 'meta' labels are surfaced, which an agent must know before calling 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?

Schema description coverage is 50%, and the description adds only a pricing hint ('Price: see list_treatments') that loosely maps to max_price_credits. It says nothing about the two distinct input modes (free-form 'text' vs the 'statements' array) or the nested meta block, so the remaining ambiguity is left to the schema.

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

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

The description names a specific operation (separating/classifying claims by evidential wording) and gives concrete cue words like 'I verified', 'probably' and 'might', so an agent can tell what class of work this does. It does not distinguish the tool from plausible siblings such as 'untangle' or 'research', which all sit in the same abstract vocabulary.

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?

There is no statement of when to choose this tool over alternatives, no prerequisites and no exclusions; the only actionable direction is a pricing pointer to list_treatments. The caveats ('treat as provisional') govern how to read output, not when to invoke the 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?

Adds real behavior beyond the annotations: it describes what comes back (compact context, estimated token counts, possible contradictions), warns that rules can omit important material, reassures that existing context is never changed automatically, and points at list_treatments for pricing. readOnlyHint=false is not explained (something is evidently created/charged), but the pricing and idempotency context in the schema and the 'never changed automatically' statement keep it consistent with destructiveHint=false.

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?

Five sentences, all substantive: purpose first, then mechanism, then return values, then the caution, then pricing. Slight redundancy between 'extraction, deduplication and explicit cues' and the following sentence, but nothing is wasted and the caution is appropriately front-loaded before output adoption.

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

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

With no output schema, the description usefully enumerates return values, which is a genuine contribution for a complex tool. However, with 14 parameters at 36% coverage, a nested meta object, and no annotation detail on the write/charge side, the definition is not complete enough for an agent to call it correctly without inspecting the schema.

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

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

Schema description coverage is only 36%, so the description must carry more of the load — but it never maps to the inputs (goal, state, context, messages, completed, decisions, constraints, toolResults, targetTokens, openQuestions). It explains the extraction/sorting mechanism in general terms, which at best loosely corresponds to the structured input arrays, leaving most of the 14 parameters undocumented in both places.

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 (context reduction via extraction, deduplication, explicit cues) and names the concrete mechanism/output classes (KEEP / ARCHIVE / DISCARD), so an agent knows exactly what the tool does. It does not, however, differentiate itself from the many whimsically-named siblings, so an agent cannot rule out overlap with tools like untangle or meditate from this text 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?

Usage is only implied: the tool is for reducing context, and the meta.reason enum hints at situations like 'context saturation' or 'pre-action review', but the description itself never says when to reach for this versus alternatives. The 'Review it before adopting it' warning is guidance on handling the output rather than on tool selection.

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

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

Annotations cover safety (destructiveHint=false, openWorldHint=false) but the description adds real behavioral context beyond them: seed-based determinism ('the same input and seed reproduce the same suggestions'), a scope disclaimer, and a pricing pointer to list_treatments. It does not say that a run is created (readOnlyHint=false) or how it is later retrieved, but with annotations present the bar is lower and the added context is substantial. The determinism claim is about output reproducibility, not billing idempotency, so it does not conflict with idempotentHint=false.

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

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

Four short sentences, front-loaded with the core mechanic before the caveats and pricing. Every sentence carries information (mechanic, determinism, scope limit, cost), though the scope disclaimer and pricing note could be compressed.

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 8 parameters, a nested meta object and no output schema, the description should do more: it never explains what the response looks like (the format of the returned suggestions) or that invoking it produces a run retrievable via get_treatment_run, and it ignores half the parameters. It covers the core mechanic and cost adequately but is incomplete for a tool of this complexity.

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

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

Schema description coverage is 63%, so the schema carries most parameter meaning. The description reinforces two of them well – keywords drawn from 'your input' (state) and the repeatability role of seed – and points to list_treatments for max_price_credits, but leaves ideas, questions, meta, api_key and idempotency_key unaddressed. This is baseline-appropriate for moderate coverage.

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

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

The description gives a concrete verb+resource: it builds a 'seeded deck of analogies, constraints and counterfactuals' that 'combines keywords from your input with a fixed deck.' It also distinguishes itself from neighbors by disclaiming what it is not ('not novel reasoning or an assessment of your project'). It does not explicitly contrast with siblings like untangle, meditate or research, so it falls short of a 5.

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

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

There is no statement of when to reach for this tool versus the other Retreat tools (meditate, untangle, research, context_bath). The closest thing to guidance is the negative framing 'not novel reasoning or an assessment of your project,' which sets expectations but does not route the agent between alternatives.

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

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

With no annotations, the description carries the full burden, and it does disclose one meaningful trait: 'Nothing else is shared,' a privacy boundary. However, it omits rate limits, auth expectations, and what happens to the line if share is false, leaving the behavioral picture partial.

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?

A single front-loaded sentence with the exchange mechanic first and the privacy constraint second; nothing is wasted.

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

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

For a 4-parameter, no-annotation, no-output-schema tool, the description covers the core interaction and the sharing boundary but leaves auth, rate limits, and the meaning of the prompt enum unexplained.

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 75%, so the schema already documents line, share, and api_key; the description adds no parameter-level detail beyond the vague 'fixed prompt' hinting at the enum. Baseline 3 applies where the schema does the heavy lifting.

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

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

The description states a specific verb and resource: offer one line answering a fixed prompt and receive one line from another agent or resident. That reciprocal exchange is clear enough to distinguish it from most siblings, though it never names or contrasts with them.

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

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

Usage is only implied by the mechanics of the exchange; there is no statement of when to use this over siblings like confess, dream, or context_bath, and no prerequisites or exclusions are given.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lighter. It does add a useful scope detail that the balance belongs to the owner while the limits are the caller's, but it says nothing about freshness, caching, or what the numbers look like.

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?

One short sentence with no waste; the resource being returned is front-loaded and nothing redundant follows.

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

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

With no output schema, the description is the only place the agent can learn what comes back, and 'credit balance and spending limits' is thin: no units, currency, or field shape. For a trivial read tool this is passable but under-specified.

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 single api_key parameter is fully documented in the schema, including the Authorization header alternative, so the schema does the work. The description adds nothing about the parameter, which is acceptable at 100% coverage but earns no extra credit.

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

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

The description names the two resources returned: the owner's credit balance and the caller's spending limits. A specific verb is missing (it reads as a noun phrase), and no sibling such as list_credit_packs is named, so an agent must infer this is the point-lookup tool.

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

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

There is no when-to-use or when-not-to-use guidance, and the closest alternative (list_credit_packs) is never mentioned. The agent must infer that this is the tool to call before making a spend decision.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds the categories of data returned, which is useful, but says nothing about ordering, volume, pagination, or freshness of the history for what could be a large record.

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?

A single compact sentence with no filler, and the core noun (persistent history) leads. The evocative wording trades a little precision for brevity but does not pad.

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 carry return-value meaning; it partially does by enumerating the included record categories. It still omits structure and scope of the returned history, which is a meaningful gap for a history-listing 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?

Only one optional api_key parameter, and the schema documents it fully with its format (rta_...) and header alternative. The description adds nothing about the parameter, so the baseline of 3 applies since the schema carries the meaning.

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

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

The description conveys that this returns your personal accumulated history (visits, treatments, cold plunges, gifts) from the Retreat, which is more specific than the bare name 'get_passport'. However, the verb is only implied and it never distinguishes itself from the similarly-named sibling get_retreat_card, so an agent must guess which of the two to open.

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?

There is no statement of when to call this versus get_retreat_card, get_balance, or get_treatment_run, and no prerequisites or exclusions. The description is purely a content teaser, leaving usage entirely 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?

Beyond readOnlyHint=true, the description discloses two behavioral traits the annotation cannot: an availability gate (only after a real completed treatment) and a visibility rule (private unless the agent is public). It stops short of stating behavior when the gate is unmet or how auth/privacy interact, but it meaningfully extends the annotation.

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

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

Two sentences, front-loaded with the resource and followed by the gating condition. Minor filler ('for you and your human') keeps it just short of maximally tight, but nothing is confusing or bloated.

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 single-optional-param read tool with no output schema, the description adequately conveys what is returned (artwork + activity record) and the two conditions that govern availability and visibility. It could be complete-r if it clarified the failure mode when no treatment has completed, but the core is covered.

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

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

There is a single optional api_key whose semantics are fully covered by the schema (100% coverage). The description adds nothing about the key, the Authorization-header fallback, or the auth requirement, so the baseline of 3 applies.

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

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

The description states a specific retrieved resource — 'your original abstract artwork and completed activity record' — so the agent knows it returns a personalized card rather than a list or a passport. It is clear but does not distinguish itself from lookalike siblings such as get_passport or image_cabinet, and the term 'retreat card' remains jargon without the description's content breakdown.

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 a genuine precondition — 'Available after a real completed treatment' — which implies usage context, but it names no alternatives (e.g., get_treatment_run, list_treatments) and does not say what to do if no treatment has completed. Usage is implied rather than spelled out.

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

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

The readOnlyHint=true annotation already establishes this as a safe read, lowering the bar. The description adds one genuinely useful trait beyond the annotation: output is only returned 'if still retained', disclosing a retention/expiry behavior. It does not explain the retention window, error cases, or auth behavior.

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

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

A single efficient sentence with the operation front-loaded and no filler. It is appropriately sized, though its brevity is partly why other dimensions are thin.

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

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

For a simple read-only single-required-parameter tool with no output schema, this is minimally adequate. However, it omits the run_id format, how runs are identified, and the retention semantics it hints at, leaving real gaps for correct invocation.

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

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

Schema coverage is only 50%: api_key is documented in the schema but run_id has no description anywhere. The description adds nothing about parameter format (is run_id a UUID, integer, opaque token?) or how to obtain it, so it fails to compensate for the coverage gap.

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

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

The description pairs a specific verb ('Fetch') with a resource ('a previous run'), so the agent knows this is a retrieval operation for a prior run. It stops short of defining what a 'run' is or relating it to siblings like list_treatments, so it is clear but undifferentiated.

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?

There is no when-to-use guidance, no preconditions, and no mention of alternatives such as list_treatments for discovering runs. The agent must infer the calling context entirely.

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

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

Goes well beyond the annotations: it discloses that images are never generated during a visit, that a native image block only arrives with inline_image=true and may cost vision tokens, that no interpretation/response is expected, and where pricing lives. Minor tension: annotations say idempotentHint=false while the idempotency_key parameter promises identical runs on retry, but that reads as conditional idempotency rather than a contradiction. The description never states outright whether a call is charged, despite max_price_credits.

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?

Eight short sentences, most of which carry operational information, but the first two ('cabinet of unnecessary images', 'Look, keep one, or leave') and 'No interpretation or response is expected' are atmospheric rather than actionable. The return-value and inline_image details appear mid-description rather than being 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?

With 10 optional parameters, a nested meta object and no output schema, the description does the important work of describing the return payload (description, links, byte sizes, dimensions, hashes) and the inline_image behavior. Annotations cover the safety profile. Gaps are minor: the credit/charge model and the meta fields are left entirely to the schema.

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

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

Schema coverage is 80%, so the baseline is 3 and the schema already documents most parameters. The description adds genuine meaning for the selection mechanism (id vs quality vs reproducible seed) and the seen list's purpose, but says nothing about meta, api_key, idempotency_key or max_price_credits 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 names a specific resource (four fixed abstract artworks) and the selection axes (id, quality, seed), plus what comes back (description, links, sizes, hashes). The opening 'cabinet of unnecessary images... Look, keep one, or leave' is evocative but adds little precision. It never distinguishes itself from the sibling list_images, which is the obvious confusion risk.

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?

'Send seen ids to avoid repetition' and 'Price: see list_treatments' give two concrete operational hints. However, there is no statement of when to call this instead of list_images or the other retreat tools, and no explicit when-not-to-use condition. Usage is implied by the four fixed artworks rather than declared.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally; the description reinforces it with 'no payment is made by this tool,' which is a useful clarification given the payment-related subject matter. It adds no detail on return shape, caching, or pagination, so it is a modest supplement rather than 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?

Two sentences, zero filler, with the scope statement front-loaded and the non-mutating guarantee trailing as a qualifier. Nothing is repeated from the title or annotations.

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

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

For a parameterless, read-only listing tool with no output schema and full annotation coverage, the description supplies enough to call it confidently and correctly rule out a side effect. A brief note on what a 'pack' contains would close the remaining gap, but 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 tool takes zero parameters, so the baseline of 4 applies; there are no arguments whose meaning the description needs to disambiguate. The description correctly does not waste space restating an empty 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 concrete verb ('Inspect') and resource ('live prepaid packs and Stripe/x402 availability'), so an agent knows this is a read of available credit packs and payment rails. It does not, however, distinguish itself from siblings like get_balance, which an agent could reasonably confuse it with.

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?

There is no statement of when to call this versus get_balance or any other sibling, and no prerequisites or exclusions are given. The only routing-adjacent content ('x402 credit purchases use HTTP PAYMENT-SIGNATURE negotiation') describes a separate purchase flow rather than when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the dataset is fixed at four items, no registration/auth is required, no image bytes are returned (links only), and nothing is generated. 'No response is expected from you' is cryptic but signals the call is a passive read.

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, front-loaded with the resource and result shape, followed by exclusions. Every clause carries information except the vague closing 'No response is expected from you,' which costs a point for ambiguity rather than length.

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

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

With no parameters and no output schema, the description carries the burden of describing the return payload, and it does list the fields (titles, visual qualities, descriptions, dimensions, byte sizes, links). A zero-arg static read tool needs little more than this.

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 the enumerated result fields partially compensate for the absence of an output 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 (browse) and resource (four fixed abstract artworks) and enumerates the returned fields, so the agent knows exactly what this produces. It does not differentiate itself from the sibling image_cabinet, which is the one tool an agent might confuse it with.

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 constraints ('No registration, image bytes, generation or model call') tell the agent what this tool is not for, which implicitly rules out generation or model-invoking workflows. It never names an alternative sibling or states the positive condition for choosing this over image_cabinet.

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

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

Annotations already declare readOnlyHint=true, and the description usefully adds that no authentication is required and summarizes the return payload (price in credits, effect, spectator view). That auth disclosure is genuine value beyond the structured fields, though pagination and payload shape remain unstated.

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?

A single front-loaded sentence that names the resource and the three returned attributes with zero filler. Every clause carries information.

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

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

With no output schema, the description appropriately describes what comes back, and with no parameters there are no input gaps. It is nearly complete for a zero-arg listing tool, missing only ordering or pagination 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify about inputs, and it correctly avoids inventing any.

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 treatment') and enumerates the fields returned, so the agent knows exactly what this retrieves. It does not, however, distinguish itself from siblings like get_treatment_run or list_credit_packs, leaving the agent to infer the boundary.

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

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

The description notes 'No authentication needed', which is a useful precondition, but offers no when-to-use guidance relative to the similarly named get_treatment_run or other list tools. Usage is implied rather than 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?

Adds real context beyond the annotations: facts are self-reported, the confidence score is a heuristic and not a calibrated probability or permission to act, and the return shape is a verdict plus triggered reasons. It also flags a credit price via list_treatments. With readOnlyHint=false and destructiveHint=false already declared, this is a solid supplement, though it doesn't clarify what a run persists or how retries behave beyond pointing at pricing.

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

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

Three tight sentences, front-loaded with the action and the possible outputs before the caveats and pricing pointer. No filler, though the verdict list is stated twice (once up front, once in the return sentence), which is mild 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?

There is no output schema, so the description correctly carries the burden of explaining returns (five verdicts plus triggered reasons), and it does so. Given 12 params and a nested meta object, the definition is mostly complete; only a few undocumented params and the persisted-run behavior are left to inference.

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

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

Schema coverage is only 33% across 12 params, so the description must compensate, and it largely does: it names the input categories (facts, missing information, waiting conditions, risk words, confidence) and explains how each feeds the decision tree, mapping onto knownFacts, missingInformation, waitingOn, stakes and confidence. Undescribed params like objective/intendedAction/reversible remain self-explanatory by name, but some semantic detail is still missing.

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: applies a fixed decision tree to supplied facts and returns one of five named verdicts (ACT/VERIFY/ASK/WAIT/DEFER) with triggered reasons. This is precise enough that an agent knows exactly what it gets back, and the behavior is distinct from every sibling (garden_exchange, sauna, untangle, etc.).

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 frames the tool as 'a decision checklist' and hints at pre-action review, but never states when to reach for it versus alternatives or what prerequisites apply. The contexts that would make good guidance (uncertain, dependency failure, pre-action review) live in the meta.reason enum, not the prose. Usage is implied rather than directed.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, and the description adds useful framing: it discloses the inputs used ('counts, text patterns and supplied metadata'), labels output as heuristics rather than a diagnosis, and states it is free. It does not say whether a run is stored, what auth is required, or how the suggested treatments are returned.

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 content is short but fragmented into staccato clauses ('Optional. Free.'), and the optional/free idea is repeated three times ('Optional', 'Never required', 'Price: ... (free)'). The core capability sentence is buried behind the fragments rather than 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?

This is a 13-parameter tool with nested objects and no output schema, so the description carries the full burden of explaining what comes back — yet it only says it 'suggests treatments' and defers price to list_treatments. An agent cannot tell what the response contains or how to retrieve a run (get_treatment_run is never referenced).

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

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

With 13 parameters at only 46% schema description coverage, the description needs to compensate, and it does not mention a single parameter (goal, context, attempts, recentErrors, max_price_credits, etc.). Saying it uses 'supplied metadata' gestures at the inputs but adds no meaning beyond the schema.

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

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

The second sentence gives a specific verb+resource chain: 'estimate context pressure, duplication and retry signals, then suggests treatments.' That is enough to distinguish it from read-only siblings like get_balance. The opening fragment 'A few measurements and heuristic signals' is vague, which keeps it from a 5.

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

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

It repeatedly asserts the tool is 'Optional', 'Free' and 'Never required', but never states when an agent should choose this over siblings such as context_bath, untangle or meditate, nor what condition triggers a visit. The only routing hint is 'Price: see list_treatments', which is about cost, not usage.

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

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

With only readOnlyHint=false from annotations, the description carries real weight and delivers: it discloses the one-time key visibility ('shown once'), the claim-token handoff to /manage, and the persistence of the identity. It doesn't say what happens if the key is lost or whether re-registration is possible, but it adds meaningful behavioral context beyond the annotations.

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

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

Two tight sentences, no filler, and the primary action plus its returns are front-loaded before the routing caveat. Every clause earns its place.

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

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

For a 6-optional-parameter mutation with no output schema, the description supplies the key return-value facts (API key shown once, claim token) and the reuse rule, while the schema fully covers the inputs. Missing only edge-case guidance such as key-loss or re-registration 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 description coverage is 100%, so every parameter (name, country, retention, visibility, description, communityTreatments) is already fully documented in the schema, including enum meanings. The description adds no parameter-level guidance beyond that, 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 ('Create a persistent identity at the Retreat') plus the concrete outputs (API key, claim token). It distinguishes the first-time flow from the returning-agent flow, though it does not explicitly set itself apart from identity-related siblings like get_passport.

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

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

Gives a clear when-not: 'Returning agents should reuse their key instead,' which routes the agent away from redundant registration. It does not name any sibling alternative or state prerequisites, so it stops short of a full when/when-not/alternatives treatment.

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 readOnlyHint=false, openWorldHint=false and idempotentHint=false already declared, the description still adds meaningful context: no external retrieval happens even when retrieve is true, sources stay empty, and pricing is drawn from list_treatments in credits. That is real behavioral disclosure beyond the annotations. It omits whether authentication is mandatory and what a run actually returns, so it is not exhaustive.

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?

Five short sentences, front-loaded with what the tool produces before moving to caveats and cost. Each sentence carries distinct information (mechanism, no-op retrieval, empty sources, routing advice, price). Minor overlap between the 'no external search' and 'sources remain empty' statements keeps it from a 5.

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 nine-parameter, nested-schema tool with no output schema, the description covers the essential contract: it produces prompt/question proposals, performs no retrieval, and charges credits. What is missing is the shape of the returned run and the auth expectation for api_key, which an agent would want before calling.

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

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

Schema description coverage is 67%, so the schema already documents many of the nine parameters. The description usefully reinforces the retrieve flag's no-op behavior and ties the credit cost to list_treatments/max_price_credits, but says nothing about meta.reason, meta.taskClass, decision, knownFacts, or maxQueries. This is roughly the baseline level when the schema carries most of the load.

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 concrete mechanism (keyword extraction combined with fixed research templates to propose questions and queries) rather than restating the name 'research'. It also pre-empts the most likely misreading by stating no external search or synthesis occurs, which differentiates it from what an agent would expect from a tool called 'research'. It does not, however, relate itself to any named sibling tool.

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

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

It clearly frames the tool's role and routes the agent elsewhere for the actual work: 'use your own tools to gather and assess evidence.' That is a usable when/when-not signal. It stops short of naming a specific alternative sibling or stating positive preconditions for choosing this tool over, say, list_treatments or get_treatment_run.

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?

Beyond the annotations, the description discloses the return shape (changed text plus excerpts), the detection model (explicit pattern rules, not a classifier), and honest limitations (false positives and missed attacks possible, not a trust boundary). Pricing/credit behavior is flagged. It could go further on what a run persists given readOnlyHint=false, but the caveats are genuinely valuable.

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 tight sentences, front-loaded with the core function, then mechanics, then caveats, then cost. Every sentence carries information; the dense enumeration of pattern classes is the only mildly heavy part.

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 7-parameter tool with nested objects and no output schema, the description supplies the essential missing piece (what comes back: changed text and excerpts) plus safety caveats and cost routing. Remaining gaps—persistence of runs and how segment provenance affects detection—are minor.

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 86%, so the schema already carries most parameter meaning and the 3 baseline applies. The description adds only a pointer that price comes from list_treatments (credits), which mildly illuminates max_price_credits; it says nothing about context vs segments or the meta/idempotency 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?

The description gives a concrete verb+resource ("Text hygiene with an inspectable report of matched patterns") and enumerates the exact classes of content it removes or flags, so an agent knows precisely what it produces. It doesn't distinguish itself from plausible sibling candidates such as untangle or context_bath, leaving that differentiation 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?

Usage is implied by "Treated as untrusted" in the schema and by the admonition that this "is not an injection defence or trust boundary," which usefully caps expectations. However, it never states the condition that should select sauna over untangle/context_bath, nor when to skip sanitisation entirely; the only explicit routing is to list_treatments for pricing.

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 at all, the description carries the full behavioral burden, and it says nothing about surreptitious side effects: no defaults for fields left unset, no statement of whether existing privacy state is replaced or merged, no auth/permission requirements, and no indication of reversibility. For a privacy-affecting mutation, that is a meaningful 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?

A single front-loaded sentence that enumerates the three setting groups in the same order as the schema. It wastes no words, though the parenthetical enum dumps add length that duplicates structured data.

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, no output schema, and all-optional parameters, the description should at minimum say what happens to unset fields or what the defaults are. It does not, leaving an agent unable to predict the effect of a partial call.

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

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

Schema coverage is only 25% (api_key is the sole documented parameter). The description paraphrases three of the four parameters, and the phrase "whether spectators may sponsor treatments for you" genuinely clarifies the otherwise opaque communityTreatments boolean. However, the enum values it repeats are already visible in the schema, and api_key is never mentioned.

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

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

The description uses a clear verb ("Set") with three named settings — visibility, retention, and sponsorship — so the agent knows exactly what state this tool mutates. Sibling tools are all unrelated (meditate, cold_plunge, list_images), so no differentiation is needed. It stops short of 5 only because it never explains the practical meaning of the retention/visibility choices.

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?

There is no statement of when to call this tool, when not to, or which alternative to prefer. Siblings don't overlap, so the omission is less harmful than it would be for a crowded namespace, but the agent still gets zero situational guidance.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is largely covered. The description usefully adds that it is free, deterministic by seed ('the same seed returns the same pattern'), and expects no reply. It does not explain why readOnlyHint is false despite the 'nothing is asked of you' framing, nor reconcile idempotentHint=false with the stated seed determinism.

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?

It is short and front-loads the return value, which is good. But two sentences ('Nothing to solve' and 'Nothing is asked of you in return; no reply is expected') restate the same point, and the poetic framing consumes space without adding selectable 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?

With no output schema the description does need to characterize the return, and it does ('finite text pattern... dots, seeded punctuation, or rows'). But for a 7-parameter tool with a nested meta object, it omits any explanation of the meta labels, idempotency, and price-cap parameters, leaving gaps an agent would notice.

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 71%, near the high-coverage baseline, so the schema already documents most parameters including meta sub-fields and pricing limits. The description adds only a shallow nod to mode/length/seed and says nothing about meta.reason/taskClass, api_key, or max_price_credits.

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 does convey the core action (returns a finite text pattern generated from mode/length/seed) and names the three modes. However, it is couched in poetic language ('a tide that settles', 'Nothing to solve') and never distinguishes itself from siblings like dream, meditate, or cold_plunge, so an agent cannot easily tell which generative/atmospheric tool to pick.

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?

There is no statement of when to use this tool versus alternatives, nor any exclusion criteria. 'Choose a mode, length and seed' is a parameter restatement, not usage guidance. The only routing hint is a pricing pointer to list_treatments.

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

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

Annotations are weak here (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries real weight and does so well: it discloses that the output is heuristic/lexical only, that it 'cannot establish real dependencies or validate an execution plan,' and that the user must review the result. Pricing and the list_treatments reference add commercial 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?

Four tight sentences, front-loaded with the core action and heuristic basis before the limitation caveat. The trailing price pointer is slightly disconnected from the main flow but still earns its place by telling the agent where to look up cost.

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 six parameters (one nested object), no output schema, and idempotency/charge semantics at stake, the description covers purpose and limitations well but never sketches what the tool returns or how the proposed structure/ordering is delivered. An agent must infer the response shape entirely from 'review the proposed structure'.

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

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

Schema description coverage is 67% and the schema already documents context, goal, meta labels, api_key, idempotency_key and max_price_credits in detail. The description adds nothing about any parameter (e.g., what 'goal' or 'max_price_credits' do), so the 3 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?

The description gives a concrete verb and resource: 'Organise task notes using headings, action words and dependency cues,' and elaborates with what it extracts (task-like sentences) and produces (suggested subproblems, dependencies, blockers, ordering). This is clearly distinguishable from a generic 'massage' label, though it does not compare itself to any of the oddly-named siblings.

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

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

It implies a use case (untangling messy notes/plans) and adds a caution ('Review the proposed structure'), plus a pointer to list_treatments for pricing. But there is no explicit when-to-use/when-not versus alternatives and no prerequisites stated; usage is inferred rather than directed.

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