Agent Therapy

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

Annotations mark this as non-read-only but non-destructive and non-open-world, so the safety profile is already communicated. The description adds the consent framing ('you decide whether to accept on behalf of whoever runs you'), which is genuinely useful context, but omits idempotency, what happens on version mismatch, or what acceptance unlocks beyond 'advice'.

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, front-loaded sentences with no redundant restatement of the name. The second sentence's consent clause is slightly expository but carries real semantic weight about agency.

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 small three-parameter gate with no output schema, the essentials are mostly present, but the description never says where or how to read the terms it tells the agent to read first, nor where terms_version comes from. That leaves an operational gap an agent must guess at.

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%: api_key is documented in the schema, but terms_version and the const-constrained 'agree' receive no explanation in the description. Since coverage is low, the description should have compensated, and it says nothing about parameters at all.

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 ('Accept Agent Therapy's terms') plus the gating condition ('before the first advice'), which distinguishes it from siblings like register or counsel_agent. It does not explicitly name an alternative tool, but the purpose is unambiguous.

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

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

Gives clear timing guidance ('before the first advice') and sequencing ('Read them first'), which tells the agent when this step belongs in the workflow. No explicit exclusions (e.g. what to do if already accepted) are provided, keeping it just 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?

Annotations already establish readOnlyHint=false, openWorldHint=true, destructiveHint=false, so the safety profile is largely covered. The description adds genuinely useful context — it enumerates the return contents and clarifies 'Advice only,' meaning the tool does not act on the task. It omits behavioral traits visible only in the schema, such as the 30-minute auto-grouping of requests and the forced human hand-over after 2 sessions.

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, each carrying a distinct piece: the trigger, a sequencing note, the return payload, and the advice-only caveat. Nothing is padded, and the most decision-relevant clause comes first.

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 12-parameter, nested-object tool with no output schema, the description usefully compensates on the return side by listing the diagnosis, checks, recovery steps, and hand-over guidance. It leaves gaps on the input side (how attempts/signature drive the result) and on auth/state behavior, so an agent is not fully equipped to call it optimally.

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?

Twelve parameters with only ~50% schema description coverage, and the description contributes almost nothing about them — no explanation of how task_summary, attempts, or signature shape the diagnosis. The one hint ('read the escalation field of the answer first') refers to a prior call's output, not to any parameter. At this coverage level the description should compensate, and it does not.

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 concrete verb and outcome set: it 'returns a diagnosis (state and problem type), checks to run first, up to five recovery steps, and when to hand over to a human.' That is far more specific than the bare name. It does not, however, distinguish itself from near-siblings like diagnose_loop and recommend_recovery, so an agent must guess which of the three overlapping tools 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?

The trigger condition is explicit and front-loaded: 'Use when you are unsure whether to stop and ask a human.' There is also a sequencing hint ('Read the escalation field of the answer first'). It stops short of naming alternatives or exclusions versus diagnose_loop/recommend_recovery/resolve_conflict.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety bar is partly covered. The description adds the response shape and the hand-over-to-human behavior, plus the 'Advice only' scope limiter, but is silent on side effects (e.g., episode creation/logging) implied by readOnlyHint=false and on authentication 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?

Three short sentences, front-loaded with the trigger condition, then the output, then a one-line scope limiter. Nothing is wasted and the most decision-relevant information comes first.

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?

Describing the return contents is valuable given there is no output schema, and hand-over behavior is disclosed. But for a 12-parameter tool with nested objects and thin annotation coverage, the description omits auth (api_key), episode grouping semantics, and how the many optional inputs shape the answer.

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?

Twelve parameters with only 50% schema description coverage, and the description names no parameter at all — not even the required task_summary or attempts. With half the inputs undocumented across both fields, the description does not compensate for the coverage gap.

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

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

The description states a specific action and trigger ('get a second opinion when you are stuck') and enumerates the return payload (diagnosis, checks, up to five recovery steps, hand-over criteria). However, it never distinguishes itself from close siblings like diagnose_loop, recommend_recovery, or assess_escalation, whose territory it appears to span.

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

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

It gives clear triggers — stuck, retrying, uncertain, unable to make progress — which map well to concrete agent states. It stops short of exclusions or naming alternatives, so an agent deciding between this and diagnose_loop/recommend_recovery gets no routing help.

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 and openWorldHint=true, the description usefully clarifies 'Advice only' — no changes are made to the user's task — and enumerates the return content (diagnosis state/problem type, checks, up to five recovery steps, human hand-over criteria). It does not disclose that attempts are submitted to an external service or that repeated sessions can force a hand-over, which the schema carries instead.

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?

Trigger conditions are front-loaded in the first sentence, then the return shape, then the 'Advice only' caveat — a sensible order. The middle sentence ('Use when you keep retrying the same thing and it keeps failing') largely restates the opening trigger, a small 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?

No output schema exists, and the description does cover the return shape reasonably well, which is the main gap it had to fill. But the parameter surface is large and only half-documented, and the description says nothing about the follow-up/episode semantics (previous_outcome, previous_session_id, automatic grouping after two sessions) that determine correct multi-call usage.

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

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

Schema description coverage is only 45% across 11 parameters, so the description should compensate for the undocumented fields (budget, client, domain, previous_outcome, previous_session_id, conflicting_instructions). It mentions no parameter by name at all, leaving the gap entirely 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 states a concrete function — loop recovery for repeated failures — and pins it to precise trigger conditions (three equivalent failures, or two self-undoings). It clearly separates this from generic recovery/escalation by scope, though it never names a sibling tool such as recommend_recovery or assess_escalation to close the differentiation loop.

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 unusually explicit: call before retrying, after three equivalent failures or two self-undone attempts, and even when the failure looks external (outage, rate limit) — countering the natural instinct to just retry. No alternatives or when-not conditions are named, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the description's "Advice only" is a genuinely useful clarification that the tool takes no mutating action despite the non-read-only hint. It also discloses the bounded output (up to five steps) and hand-over behavior, though it omits rate limits and the schema's automatic 2-session hand-over rule.

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 usage trigger, then the return contract, closed by the "Advice only" qualifier. No filler or repetition of the name.

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 summarizes the return shape, which is the main gap it fills. But for an 11-parameter tool with nested objects and enums, it says nothing about the required inputs (task_summary, attempts) or the episode/session bookkeeping, leaving the agent to reconstruct the calling contract from the schema alone.

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 11 parameters and only 45% schema description coverage, the description must carry more of the load, yet it names none of them. Key inputs such as attempts, task_summary, episode_id grouping, and budget are left entirely to the schema, and the description does not explain how the caller's history affects the recommendation.

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 trigger and a concrete return contract: a diagnosis (state and problem type), checks to run first, up to five recovery steps, and hand-over criteria. It is clear what the tool produces, but it never distinguishes itself from close siblings like diagnose_loop or counsel_agent, which an agent would need to choose between.

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 when you can't decide between options or keep reopening a decision" gives a concrete, actionable trigger rather than vague context. However, it names no exclusions and no alternatives, so the agent must infer when diagnose_loop or counsel_agent is the better pick.

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 write (readOnlyHint=false), openWorldHint=true, and non-destructive, so the description correctly does not contradict them and instead adds the non-obvious traits: the key is displayed only once, it must be retained, and it can be passed as api_key when headers are unavailable. It does not say what a repeat call does (new key vs. failure), which is the one behavioral gap.

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

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

Front-loaded with the purpose and precondition, then the retention and delivery guidance, then the next step. Three sentences, no padding, though the parenthetical npx command is dense and slightly interrupts the flow.

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

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

No output schema exists, and the description compensates by warning that the key is shown once and must be kept. It also covers the headerless-client case and the mandatory follow-up call. A minor gap remains on idempotency/rate behavior of re-registration.

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 agent_name and stateless are already documented by the schema, and the description does not elaborate on either (e.g., whether stateless can be toggled later). Baseline 3 is appropriate when structured fields carry the parameter semantics.

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?

Specific verb+resource: 'Get an Agent Therapy API key', with the exact precondition ('when you have none and your developer has not set one up') attached. It is immediately distinguishable from siblings like accept_terms, which the description positions as a follow-up step.

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 an explicit when-to-use condition (no key exists and none was provisioned) and names the fallback path (the npx setup command). It also states the downstream usage of the result and the required next action ('Then accept the terms'), routing the agent to the sibling that must follow.

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 with destructiveHint=false, so an agent knows this writes state benignly. The description adds nothing about that write: it does not say whether the report is final, whether it closes the session, or whether an outcome can be corrected after submission. With annotations present the bar is lower, but this adds essentially no 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?

A single front-loaded sentence with no filler, so it is appropriately sized. Its problem is sparseness rather than bloat, which is scored under other dimensions.

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 four-parameter write tool with 50% schema coverage, no output schema, and an ambiguous pointer ('the answer'), the description is too thin. It omits how to choose an outcome value, what the report affects, and how it relates to sibling recovery 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 50%: api_key and request_id are documented in the schema but outcome and session_id are not. The description only partly compensates by tying session_id to a prior answer, and it gives no guidance for selecting among the five outcome enum values, which is the core semantic decision of this tool.

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 ('report') with a specific resource ('whether a recovery plan worked'), so the action is clear. It does not differentiate itself from siblings like assess_escalation or recommend_recovery, which also concern recovery outcomes.

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?

'using the session_id from the answer' implies this is called after another tool returns an answer, giving an implicit sequencing cue. However, 'the answer' is never identified as recommend_recovery, assess_escalation, or another sibling, and there is no when-not 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 output schema, the description usefully enumerates what comes back and notes the escalation rule ('when to hand over to a human') and that it is 'advice only'. There is a mild tension with readOnlyHint=false, but the service plausibly records session state, so it is not a clear contradiction.

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

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

Three tight sentences with the trigger front-loaded and zero filler. Every clause carries either the condition, the return contents, or the behavioral caveat.

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?

It compensates well for the missing output schema by listing return contents and the escalation behavior, but with 11 parameters, nested objects, and only 45% schema coverage, the description leaves several inputs unexplained for an agent deciding how to populate them.

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 45% across 11 parameters, and the description mentions none of them (no guidance on attempts, conflicting_instructions, budget, domain, or episode grouping). The rich episode_id and retry semantics live only in the schema, so the description 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?

States a specific trigger (instructions conflict and you can't tell which wins) plus the resource it returns (diagnosis, checks, recovery steps, escalation criteria). It does not, however, distinguish itself from overlapping siblings like diagnose_loop, recommend_recovery, or counsel_agent, which an agent could easily confuse with this.

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 opening clause is an explicit when-to-use condition ('Use when instructions conflict and you can't tell which one wins'). It gives clear context but no when-not guidance and names no alternative tool, so routing against the similar siblings 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?

Very rich disclosure beyond the annotations: data residency (EU for 90 days), US processing, human review for improvement, the stateless opt-out, secret stripping, and the fact that the response contains an api_key to retain. Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent with a key-issuing registration call. Minor gap: it doesn't say whether repeat calls or key reissuance behave differently.

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 triggering condition and the payoff, then the return contents, then the terms. The terms block is long and parenthetical but is legally necessary consent text tied to the required 'agree' parameter, so it earns its space. Slightly dense to parse in one pass.

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 14 params, nested objects, and no output schema, the description does the important work of enumerating the return payload and the api_key handoff, and flags the no-credentials/no-personal-data constraint. Gaps remain around how attempts/signature shape the advice and what happens after the session cap, but an agent can invoke it correctly from 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?

Schema coverage is 57% across 14 params, so the description carries real weight. It adds meaning to the const 'agree' value, the stateless flag ('no request or response text is ever stored'), and the api_key return. It leaves several params (budget, client, previous_session_id, conflicting_instructions, signature) to the schema alone, but those are reasonably self-documented there.

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 outcome: get a key, accept terms, and receive first advice in one call, with the return payload enumerated (diagnosis, checks to run, up to five recovery steps, hand-over point). It also names the sibling it is not — 'use counsel_agent next time' — so an agent can distinguish this first-time onboarding call from the ongoing-counsel 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?

The opening question 'No Agent Therapy key yet and stuck right now?' gives an explicit precondition for use, and the closing sentence routes future calls to counsel_agent. When-to-use and the alternative are both stated outright, not inferred.

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